Edge for Private Cloud v. 4.17.05
Monetization Services is an extension to Apigee Edge, hence it does not run as a standalone process. It runs within any existing Apigee Edge setup.
Monetization requirements
- If you are installing Monetization on an Edge topology that use multiple Management Server nodes, such as a 13-node installation, then you must install both Edge Management Server nodes before installing Monetization.
- To install Monetization on Edge where the Edge installation has multiple Postgres nodes, the Postgres nodes must be configured in Master/Standby mode. You cannot install Monetization on Edge if you have multiple Postgres master nodes. For more, see Set up Master-Standby Replication for Postgres.
Installation overview
The following steps illustrate how to add Monetization Services on an existing Apigee Edge installation:
- Use the apigee-setup
utility to update the Apigee Management Server node to enable the Monetization Services, for
example, catalog management, limits and notifications configuration, billing and
reporting.
If you have multiple Management Server nodes, such as a 13-node installation, then you must install both Edge Management Server nodes before installing Monetization. - Use the apigee-setup utility to update the Apigee Message Processor to enable the runtime components of the Monetization Services, for example, transaction recording policy and limit enforcement. If you have multiple Message Processors, install Monetization on all of them.
- Perform the Monetization onboarding process for your Edge organizations.
- Configure the Developer Services portal to support monetization. For more information, see http://apigee.com/docs/monetization/content/configure-monetization-developer-portal.
Creating a silent configuration file for Monetization
Shown below is an example silent configuration file for a Monetization installation. Edit this file as necessary for your configuration. Use the -f option to setup.sh to include this file.
Note: Typically, you add these properties to the same configuration file that you used to install Edge, as shown in Install Edge components on a node.
# Edge configuration properties # Specify IP address or DNS name of node. IP1=192.168.1.1 # Management Server, OpenLDAP, UI, ZooKeeper, Cassandra IP2=192.168.1.2 # ZooKeeper, Cassandra IP3=192.168.1.3 # ZooKeeper, Cassandra IP4=192.168.1.4 # Router, Message Processor IP5=192.168.1.5 # Router, Message Processor IP6=192.168.1.6 # Qpid IP7=192.168.1.7 # Qpid IP8=192.168.1.8 # Postgres IP9=192.168.1.9 # Postgres # Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost. HOSTIP=$(hostname -i) # Edge sys admin credentials ADMIN_EMAIL=your@email.com APIGEE_ADMINPW=yourPassword # If omitted, you are prompted for it. # Specify the Management Server port. APIGEE_PORT_HTTP_MS=8080 # # Monetization configuration properties. # # Postgres credentials from Edge installation. PG_USER=apigee # Default from Edge installation PG_PWD=postgres # Default from Edge installation # Specify Postgres server. MO_PG_HOST="$IP8" # Only specify one Postgres node. # Create a Postgres user for Monetization. # Default username is "postgre". # If you specify a different user, that user must already exist. MO_PG_USER=postgre MO_PG_PASSWD=moUserPWord # Specify one ZooKeeper host. # Ensure this is a ZooKeeper leader node in a multi-datacenter environment. ZK_HOSTS="$IP2" # Specify Cassandra information. # Ensure CASS_HOSTS is set to the same value as when you installed Edge. # Must use IP addresses for CASS_HOSTS, not DNS names. CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1" # Default is "Apigee", unless it was changed during Edge install. CASS_CLUSTERNAME=Apigee # Cassandra uname/pword required only if you enabled Cassandra authentication. # CASS_USERNAME= # CASS_PASSWORD= # Specify the region. # Default is dc-1 unless you are in a multi-datacenter environment. REGION=dc-1 # If your Edge config file did not specify SMTP information, add it. # Monetization requires an SMTP server. SMTPHOST=smtp.gmail.com SMTPPORT=465 SMTPUSER=your@email.com SMTPPASSWORD=yourEmailPassword SMTPSSL=y SMTPMAILFROM="My Company <myco@company.com>"Notes:
- If your Edge config file did not specify SMTP information, add it. Monetization requires an SMTP server.
- In a single data center installation, all ZooKeeper nodes are by default configures as leaders. When you are installing Edge across multiple data centers, some ZooKeeper nodes will be configured as observers. Ensure that the ZK_HOSTS property above specifies a leader node in a multiple data center installation.
- If you enable Cassandra authentication, you can pass the Cassandra user name and password
by using the following properties:
CASS_USERNAME
CASS_PASSWORD
Integrate Monetization Services with all Management Servers
Use the following procedure to integrate monetization on Management Server nodes.
- If you are installing Monetization on an Edge topology that uses multiple Management Server nodes, such as a 13-node installation, then ensure that you installed both Management Server nodes before installing Monetization.
- On the Management Server node, run the setup script:
> /opt/apigee/apigee-setup/bin/setup.sh -p mo -f configFile
The “-p mo” option specifies to integrate Monetization.
The configuration file must be accessible or readable by the "apigee" user. - If you are installing Monetization on multiple Management Server nodes, repeat step 2 on the second Management Server node.
On successful configuration, an RDBMS schema for Monetization Services is created in the PostgreSQL database. This completes the integration of Monetization Services and its associated components with Postgres Server.
Integrate Monetization Services with all Message Processors
Use the following procedure to integrate monetization on all Message Processor nodes.
- On the first Message Processor node, at the command prompt, run the setup script:
> /opt/apigee/apigee-setup/bin/setup.sh -p mo -f configFile
The “-p mo” option specifies to integrate Monetization.
The configuration file must be accessible or readable by the "apigee" user. - Repeat this procedure on all Message Processor nodes.
On successful configuration, the Message Processor is updated with Monetization Services. This completes the integration of Monetization Services and its associated components with the Message Processors.
Monetization Onboarding
To create a new organization with monetization enabled, you first create the organization as you would for any new organization. For more information, see Onboard an organization.
Additional Onboarding to enable Monetization for an organization
To complete monetization onboarding of an organization, you have to:
- Create the monetization group: mxgroup.
- Add Qpid to the group.
- Enable monetization for the organization.
- Enable notification settings for the organization.
- Repeat this process for all organizations where you want to enable Monetization.
Use the enable-monetization command to perform all of these tasks. This script takes a configuration file containing the following properties:
MSIP=IPorDNSofManagementServer APIGEE_PORT_HTTP_MS=8080 # Default is 8080. ADMIN_EMAIL=your@email.com APIGEE_ADMINPW=yourPassword # If omitted, you are prompted for it. # Must use IP addresses for CASS_HOSTS, not DNS names. CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1" # Space-separated list IP/DNS names of all Qpid nodes in the data center being configured. QPID_HOST="$IP6 $IP7" QPID_PORT=8083 # Default is 8083. REGION=dc-1 ORG_NAME=myorg # The Edge org where you want to enable monetization. MX_GROUP=mxgroup # Default Monetization group.
Notes:
- Set CASS_HOSTS and REGION to the same values as you used when installing Monetization.
- If you are enabling Monetization in a multiple data center configuration:
- You must repeat the onboarding process on the Management Server in each data center.
- The configuration file should only list the Qpid nodes in the data center being configured.
To run the script:
- Invoke the script:
> /opt/apigee/apigee-service/bin/apigee-service apigee-provision enable-monetization -f configFile
The configuration file must be accessible or readable by the "apigee" user.
If you have multiple Management Servers, you only have to run this script on one of them.
This script replicates the organization, products, developers and applications from Cassandra database to Monetization PostgreSQL database. After successful installation of Monetization Services the data is synchronized automatically. - Repeat this procedure for every organization where you want to enable Monetization.
- If you are in a multiple data center environment, repeat this process on the Management Server in the other data center. Ensure that the config file list only the Qpid nodes in the data center being configured.
When you next log in to the Edge UI, you see the Monetization entry in the top-level menu for the organization:
Configure the Developer Services portal
To configure the Developer Services portal to support monetization, see http://apigee.com/docs/monetization/content/configure-monetization-developer-portal.
Adding a Management Server node to a Monetization Installation
If you add a Management Server to an existing Edge installation, you must ensure that you add Monetization services to the new Management Server and configure all Management Servers so they can communicate.
To add a Management Server:
- Install the new Management Server.
- Install Monetization on the new Management Server.
- On the original Management Server, call the following:
> /opt/apigee/apigee-service/bin/apigee-service edge-mint-management-server mint-configure-mgmt-cluster - Restart the original Management Server:
> /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart - On the new Management Server, call the following:
> /opt/apigee/apigee-service/bin/apigee-service edge-mint-management-server mint-configure-mgmt-cluster - Restart the new Management Server:
> /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
Additional configuration
Provide Billing Documents as PDF Files
Monetization displays billing documents to end users in HTML format. To provide billing documents as PDF files, you can integrate Monetization with a billing system that provides PDF generation or license a supported third-party PDF library.
Configure Organization Settings
Backend settings: The following table lists the organization level attributes that are available to configure a mint organization. You can use a PUT call to add/update these attributes as shown below:
> curl -u ${ADMIN_EMAIL}:${ADMINPW} -v http://<management-ip>:8080/v1/organizations/{orgId} -d '{org object with attributes}' -X PUT
For example, the output of the above CURL command will look something like this:
{
...
"displayName": "Orgnization name",
"name": "org4",
"properties": {
"property": [
...
{
"name": "MINT_CURRENCY",
"value": "USD"
},
{
"name": "MINT_COUNTRY",
"value": "US"
},
{
"name": "MINT_TIMEZONE",
"value": "GMT"
}
]
}
}
Attributes |
Description |
---|---|
MINT_TAX_MODEL |
Accepted values are DISCLOSED, UNDISCLOSED, HYBRID (default is null) |
MINT_CURRENCY |
ISO currency code (default is null) |
MINT_TAX_NEXUS |
Tax nexus (default is null) |
MINT_DEFAULT_PROD_TAX_CATEGORY |
Default product tax category (default is null) |
MINT_IS_GROUP_ORG |
IS group organization (default is false) |
MINT_HAS_BROKER |
Has broken (default is false) |
MINT_TIMEZONE |
Timezone (default is null) |
MINT_TAX_ENGINE_EXTERNAL_ID |
Tax engine ID (default is null) |
MINT_COUNTRY |
Organization's country (default is null) |
MINT_REG_NO |
Organization's registration number, United Kingdom gives different number than tax ID (default is null) |
MINT_BILLING_CYCLE_TYPE |
PRORATED, CALENDAR_MONTH (default is CALENDAR_MONTH) |
MINT_SUPPORTED_BILLING_TYPE |
PREPAID/POSTPAID/BOTH (default is PREPAID) |
MINT_IS_SEPARATE_INV_FOR_FEES |
Indicates whether a separate fee invoice should be generated (default is false) |
MINT_ISSUE_NETTING_STMT |
Indicates whether netting statement should be issued (default is false) |
MINT_NETTING_STMT_PER_CURRENCY |
Indicates whether netting statement should be generated per currency (default is false) |
MINT_HAS_SELF_BILLING |
Indicates whether the organization has self billing (default is false) |
MINT_SELF_BILLING_FOR_ALL_DEV |
Indicates whether the organization has self billing for all developers(default is false) |
MINT_HAS_SEPARATE_INV_FOR_PROD |
Indicates whether the organization has separate invoice per product (default is false) |
MINT_HAS_BILLING_ADJUSTMENT |
Indicates whether the organization supports billing adjustments (default is false) |
features.isMonetizationEnabled |
Used by the management UI to display monetization specific menu (default is false) |
ui.config.isOperator |
Used by management UI to display provider as Operator verses Organization (default is true) |
For configuring business organization settings using the management UI, see http://apigee.com/docs/monetization-services/content/get-started-using-monetization-services.
Note: If you are using Monetization Services Limits and Notifications features, please instruct your developers to attach a Limit Policy in the proxy flow after the access token validation policy.
Limit Policy is an explicit policy designed to block an API call if certain limit has been reached. The policy checks business limits and raises a fault if there are any limits exceeding the configured value. This is an extension of raise fault policy but the conditions are derived from business variables.
A UI template is available in the management UI for proxy developers. Proxy developer should attach mint policy in the message flow. Upon execution of this policy the fault will be raised with the fault response as per policy. If ContinueOnError is set to true then the fault will not be raised and flow variables "mint.limitsViolated", "mint.isDeveloperSuspended" and "mint.limitsPolicyError" variables will be set which could be used for further exception handling if required.