Creating Provisioning Tags

About Provisioning Tags

You use service provisioning to make changes on the network based on changes in service status in BRM or changes to the product offerings that customers purchase. For example:

If a customer purchases a charge offer that includes voice mail, you can send commands to create the voice mailbox on the network when the charge offer is purchased.
If a customer changes the status of a service, you can send a command to the network to activate or deactivate the service.
You can activate or deactivate service extensions and supplementary services; such as call forwarding.

In this example, the email service is associated with three charge offers. Each charge offer has an associated provisioning tag. Each provisioning tag defines a different service configuration based on mailbox size. When a customer signs up for email service and purchases a package, the mailbox size is configured according to the associated provision tag.

Service	Charge Offer	Provisioning Tag	Description
/service/email	Basic Email	Basic	Sets the minimum mailbox size to 0MB, the maximum mailbox size to 10MB, and specifies the path to the mail server.
/service/email	Regular Email	Regular	Sets the minimum mailbox size to 0MB, the maximum mailbox size to 20MB, and specifies the path to the mail server.
/service/email	Power Email	Power	Sets the minimum mailbox size to 0MB, the maximum mailbox size to 30MB, and specifies the path to the mail server.

Service

Charge Offer

Provisioning Tag

Description

/service/email

Basic

Email

Basic

Sets the minimum mailbox size to 0MB, the maximum mailbox size to 10MB, and specifies the path to the mail server.

/service/email

Regular

Email

Regular

Sets the minimum mailbox size to 0MB, the maximum mailbox size to 20MB, and specifies the path to the mail server.

/service/email

Power

Email

Power

Sets the minimum mailbox size to 0MB, the maximum mailbox size to 30MB, and specifies the path to the mail server.

You can use one of the following methods to define provisioning tags, depending on what the tag is for:

Provisioning tag framework: You create provisioning tags by defining them in an XML file that is loaded into a configuration object in BRM. You can create provisioning tags for any service or account.

You also might need to add the tag to the provisioning policy source file and compile the file.
Note:
- For telco services, use Services Framework Manager to define provisioning tags in most cases. You must use Services Framework Manager if the provisioning tag creates supplementary services or service extensions.
- For nontelco services, the provisioning tag framework is the recommended method of creating provisioning tags.
Telco tag text file: For telco services only, you can create service provisioning tags by defining them in a text file and then loading the file into BRM. You can include supplementary services in the tags.
Provisioning policy source file: You can define charge offer provisioning tags by editing and compiling the policy file that is the source file for all provisioning operations.

Note:

The provisioning tag framework is the preferable method for creating provisioning tags.

Deciding Which Provisioning Tag Method to Use

For telco services, you should create provisioning tags by using one of these methods. The order of preference is shown below.

Provisioning tag framework.
Telco tag text file.
Provisioning policy source file.

For nontelco services, you should create provisioning tags by using one of these methods. The order of preference is shown below:

Provisioning tag framework.
Provisioning policy source file.

Using the Provisioning Tag Framework

You can create service or account provisioning tags using the provisioning tag framework. This framework stores provisioning tags in the /config/provisioning_tag object.

Note:

To create most provisioning tags for telco services, use the load_pin_telco_tags utility.

You define a provisioning tag by specifying the services to which it applies and the opcodes to run when the charge offer or discount containing the tag is purchased or canceled. You might need to create custom opcodes for some provisioning tags.

To create a provisioning tag using this framework, do the following:

Configure the provisioning tag in the pin_config_provisioning_tags.xml file.
Load the provisioning tag configuration into the /config/provisioning_tag object with the load_config_provisioning_tags utility.
Add the tag to the provisioning policy source file and compile the file. You do this if you will include the provisioning tag in a charge offer and if the tag uses a service associated with the __DEFAULT__ provisioning tag.

Configuring Provisioning Tags

To create provisioning tags, you configure the provisioning tags configuration file, pin_config_provisioning_tags.xml. This file is located in the BRM_home/sys/data/config directory.

To define a provisioning tag in this configuration file, you specify the following:

A unique name for the provisioning tag.

Note:

The provisioning tag for a charge offer or discount must be the name of the offer profile with which the charge offer or discount is associated.
For a service tag, the permitted services.
For an account tag, /account.
The name and number of each opcode to run when the charge offer or discount containing the provisioning tag is purchased or canceled. These opcodes contain the business logic to perform the actual provisioning, such as creating a profile.
Parameters that specify the fields to be added to each opcode's input flist and the value for each field.
Note:
- Do not remove existing provisioning tags from pin_config_provisioning_tags.xml when adding new tags unless you want existing tags removed from the /config/provisioning_tag objects in the database.
- When you load pin_config_provisioning_tags.xml, all existing instances of /config/provisioning_tag are removed from the database, so only the provisioning tags defined in the file when you load it are in the database.

Table 6-1 lists the elements in the pin_config_provisioning_tags.xml file, the syntax to use for each element, and a description of how to specify each element. The syntax is based on the default version of the file:

Table 6-1 Elements in pin_config_provisioning_tags XML File

Element	Syntax	Description
BusinessConfiguration	<BusinessConfiguration xmlns="http://www.portal.com/ schemas/BusinessConfig" xmlns:xsi="http://www.w3.org/ 2001/XMLSchema-instance" xsi:schemaLocation="http://www.portal.com/schemas/ BusinessConfig business_configuration.xsd">	The root element common to all BRM configurations.
ProvisioningTag Configuration	<ProvisioningTagConfiguration>	Opens the provisioning tag configuration. Contains the ProvisioningTagList element.
ProvisioningTagList	<ProvisioningTagList>	Contains all the provisioning tag definitions.
ProvisioningTag	<ProvisioningTag name= "__DEFAULT__">	Contains the definition of a provisioning tag and specifies the tag's name.
PermittedTypes	<PermittedTypes>/service/ip </PermittedTypes>	Specifies a service or account valid for the provisioning tag. One or more of these tags can be part of a provisioning tag definition. When the API for getting a list of provisioning tags is called, the array of permitted types is looked up; only provisioning tags applicable to the specified service are returned.
OpcodeList	<OpcodeList>	Contains the definition of one opcode. The opcodes specified for a provisioning tag contain the business logic required for provisioning when purchasing and canceling a charge offer. A provisioning tag can include multiple opcodes.
OpcodeName	<OpcodeName> PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING </OpcodeName>	Specifies the opcode's name.
OpcodeNumber	<OpcodeNumber>417 </OpcodeNumber>	Specifies the hard-coded number for an opcode. To find an opcode's number, see the opcode header files in the BRM_home/include/ops directory.
OpcodeMode	<OpcodeMode>0</OpcodeMode>	Indicates when the opcode should be called, as follows: 0: on charge offer or discount purchase 1: on charge offer or discount cancellation 2: on both purchase and cancellation
OpcodeParamsList	<OpcodeParamsList>	Defines a parameter for an opcode. You can have multiple parameters. Each parameter is a name-value pair.
OpcodeParamName	<OpcodeParamName>PIN_FLD_POID </OpcodeParamName>	Specifies a field name to be added to the input flist. If the field is part of a substruct or array, use a period to separate the substruct or array name and the field name. For example: PIN_FLD_EVENT.PIN_FLD_ACCOUNT_OBJ
OpcodeParamValue	<OpcodeParamValue>$SERVICE$ </OpcodeParamValue>	Specifies the value of the field. For certain values not known until run time, you can use a variable, such as $SERVICE$.

Specifying an Opcode in a Provisioning Tag to Create an ERA

When defining a configuration for the provisioning tag framework, you specify one or more opcodes to perform an action, such as creating an ERA. You can specify that an opcode run when a charge offer or discount is purchased, canceled, or both. You can use an existing opcode or design a custom opcode.

If the provisioning tag is designed to create an ERA, you can specify that the PCM_OP_SUBSCRIPTION_PROVISION_ERA opcode run at both purchase and cancellation time. This opcode creates, modifies, or deletes a profile (/profile object). ERAs are stored in profiles.

The actions PCM_OP_SUBSCRIPTION_PROVISION_ERA takes depends on the value specified for the PIN_FLD_ACTION parameter in the provisioning tag:

If PIN_FLD_ACTION is Purchase, the opcode checks if a profile already exists. If the profile does not exist, the opcode calls PCM_OP_CUST_CREATE_PROFILE to create the profile. If the profile does exist, the opcode calls PCM_OP_CUST_MODIFY_PROFILE to add data passed in from the input flist and to increment the reference counter by 1.
If PIN_FLD_ACTION is Cancel, the opcode decrements the reference counter by 1. If the counter is 0, the opcode calls PCM_OP_CUST_DELETE_PROFILE to delete the profile.

For example, you can create a friends and family ERA for a service by calling the PCM_OP_SUBSCRIPTION_PROVISION_ERA at purchase time with the parameters in Table 6-2:

Table 6-2 PCM_OP_SUBSCRIPTION_PROVISION_ERA Parameters

OpcodeParamName	OpcodeParamValue
PIN_FLD_POID	0.0.0.0 /profile/serv_extrating -1
PIN_FLD_ACCOUNT_OBJ	$ACCOUNT$
PIN_FLD_FLAGS	0
PIN_FLD_SERVICE_OBJ	$SERVICE$
PIN_FLD_STR_VAL	12, 13
PIN_FLD_NAME	FRIENDS_FAMILY
PIN_FLD_INHERITED_INFO. PIN_FLD_EXTRATING. PIN_FLD_LABEL	MYFRIENDS

These name-value pairs indicate that an ERA named FRIENDS_FAMILY and an ERA label named MYFRIENDS are created. Because both the account and service POIDs are specified, the opcode creates a service profile (/profile/serv_extrating) object. If the service POID was not specified, the opcode would create an account profile (/profile/acct_extrating) object.

Note:

PIN_FLD_POID is the POID, in string format, of the object the provisioning tag creates. This is converted to a POID when the opcode runs. If you are using multiple database schemas, the string is converted to the correct schema database number.
For a service profile, the POID type is /profile/serv_extrating, as in the previous example. For an account profile, the POID type is /profile/acct_extrating.
PIN_FLD_FLAGS specifies that PCM_OP_SUBSCRIPTION_PROVISION_ERA is called at purchase time.

You must include the opcode twice in a provisioning tag, once with PIN_FLD_FLAGS set to 0 and once with PIN_FLD_FLAGS set to 1, so that it runs both at purchase and cancellation time.

PIN_FLD_STR_VAL specifies that the profile name and profile description are localized and are stored in the /string object under string IDs 12 and 13.
PIN_FLD_ACCOUNT_OBJ and PIN_FLD_SERVICE_OBJ use variables.

Variables for Parameter Values

You can use the following variables in Table 6-3 to specify certain values available only at the time the opcode is run:

Table 6-3 Run-Time Variables for Parameters

Variable	Description
$ACCOUNT$	Account object POID
$SERVICE$	Service object POID
$PRODUCT$	Charge offer POID
$DISCOUNT$	Discount offer POID
$OFFERING$	POID of the purchased charge offer or discount offer
$PROVTAG$	Provisioning tag

Default Provisioning Tag

The default /config/provisioning_tag object contains the __DEFAULT__ provisioning tag. This tag is defined in the default pin_config_provisioning_tags.xml file. The tag calls the following opcodes:

PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING, on charge offer purchase.
PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING, on charge offer cancellation.

If you have customized these opcodes, they set and clear fields in /service objects when a charge offer is purchased and canceled. If you have not customized these opcodes, you do not need to use them. You can specify other opcodes in the provisioning tags file to perform necessary actions.

The __DEFAULT__ provisioning tag is always called for specified services when a charge offer is purchased or canceled, so you do not need to include these opcodes in any other provisioning tags you define. See the default pin_config_provisioning_tags.xml file for the list of services.

Using Custom Opcodes

You can create custom opcodes to perform actions not supported by existing opcodes and specify the custom opcodes in the provisioning tags configuration file. For example, you can write an opcode to add fields to a /service object.

Modifying Provisioning Tags

You use provision tags as the names of offer profiles associated with charge offers and discounts. If you modify a provision tag used as an offer profile, be sure to modify the corresponding offer profile name accordingly.

Note:

Do not remove existing provisioning tags from pin_config_provisioning_tags.xml when adding new tags unless you want existing tags removed from the /config/provisioning_tag objects in the database.
When you load pin_config_provisioning_tags.xml, all existing instances of /config/provisioning_tag are removed from the database, so only the provisioning tags defined in the file when you load it are in the database.

Loading Provisioning Tag Configurations

After you configure provisioning tags in the pin_config_provisioning_tags.xml file, load the tags into the database with the load_config_provisioning_tags utility.

Note:

The utility that loads provisioning tags into the database overwrites existing provisioning tags. When updating provisioning tags, you cannot load new provisioning tags only. You must load the complete set of provisioning tags each time you run the utility.

To load provisioning tag configurations:

Go to the directory in which the pin_config_provisioning_tags.xml file is located. The default location is BRM_home/sys/data/config.
Use the following command to run the load_config_provisioning_tags utility:
```
load_config_provisioning_tags pin_config_provisioning_tags.xml 
```
Note:
- When you run the utility, thepin_config_provisioning_tags.xmland business_configuration.xsd files must be in the same directory. By default, both files are in BRM_home/sys/data/config.
- This utility needs a configuration (pin.conf) file in the directory from which you run the utility.
If you do not run the utility from the directory in which pin_config_provisioning_tags.xml is located, include the complete path to the file, for example:
```
load_config_provisioning_tags BRM_home/sys/data/config/pin_config_provisioning_tags.xml 
```
For more information, see load_config_provisioning_tags.
Stop and restart the Connection Manager (CM).
To verify that the provisioning tags were loaded, display the /config/provisioning_tag object by using the Object Browser or the robj command with the testnap utility.

Modifying and Compiling the Provisioning Policy Source File

If a provisioning tag defined in the provisioning tag framework uses the PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING policy opcode, you must add the tag to the fm_subscription_pol_provisioning.c file and recompile the file.

You can also use the PCM_OP_PROV_POL_UPDATE_SVC_ORDER opcode to customize service orders. See BRM Opcode Guide.

A provisioning tag uses PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING opcode if it is included in a charge offer and if it uses a service associated with the __DEFAULT__ provisioning tag.

Modifying and compiling the provisioning policy source file enables PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING to handle the tags.

To modify the provisioning policy source file for provisioning tags created using the provisioning tag framework:

Open the BRM_home/source/sys/fm_subscription_pol/fm_subscription_pol_provisioning.c file.
Add the provisioning tag name to the service_info table for the appropriate service.

For example, to add a provisioning tag called test to /service/ip, change this code:
```
static char *tags_ip[] = {
  "example",
  NULL    /* MUST BE LAST! */
};
```
to the following:
```
static char *tags_ip[] = {
"example",
"test",
  NULL    /* MUST BE LAST! */
};
```

Add code in the plp function to handle the new tag. You do this in the PROVISIONING FUNCTIONS section. The functions are grouped by service.

For example, to add the provisioning tag test to /service/ip, change this code:

static void
plp_ip(pcm_context_t *ctxp, poid_t *svc_obj_p, int32 buy,
  char *tag, pin_errbuf_t *ebufp)
{
  if (strcmp(tag, "example") == 0) {
    plp_example(ctxp, svc_obj_p, buy, tag, ebufp);
  }
  else{
    plp_ssg(ctxp, svc_obj_p, buy, tag, ebufp);
  }
}

to the following:

static void
plp_ip(pcm_context_t *ctxp, poid_t *svc_obj_p, int32 buy,
  char *tag, pin_errbuf_t *ebufp)
{
  if (strcmp(tag, "example") == 0) {
    plp_example(ctxp, svc_obj_p, buy, tag, ebufp);
  }
  else if (strcmp(tag, "test") == 0) {
    /*skip*/
  }else{
    plp_ssg(ctxp, svc_obj_p, buy, tag, ebufp);
  }
}

Compile and save the file.

Sample Provisioning Tag XML File

Following is the default provisioning tag XML file. This file defines the provisioning tag named __DEFAULT__, which includes several permitted services and two opcodes:

<?xml version="1.0" encoding="UTF-8"?>

<BusinessConfiguration 
    xmlns="http://www.portal.com/schemas/BusinessConfig"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.portal.com/schemas/BusinessConfig business_configuration.xsd">

    <ProvisioningTagConfiguration>
    <ProvisioningTagList>

        <ProvisioningTag name="__DEFAULT__">

            <PermittedTypes>/service/email</PermittedTypes>
            <PermittedTypes>/service/ip/gprs</PermittedTypes>
            <PermittedTypes>/service/content</PermittedTypes>
            <PermittedTypes>/service/vpdn</PermittedTypes>
            <PermittedTypes>/service/ip</PermittedTypes>
            <PermittedTypes>/service/ip/gprs</PermittedTypes>
            <PermittedTypes>/service/telco</PermittedTypes>
            <PermittedTypes>/service/telco/gsm</PermittedTypes>
            <PermittedTypes>/service/telco/gsm/data</PermittedTypes>
            <PermittedTypes>/service/telco/gsm/fax</PermittedTypes>
            <PermittedTypes>/service/telco/gsm/sms</PermittedTypes>
            <PermittedTypes>/service/telco/gsm/telephony</PermittedTypes>

            <OpcodeList>
                <OpcodeName>PCM_OP_SUBSCRIPTION_POL_PURCHASE_PROD_PROVISIONING</OpcodeName>
                <OpcodeNumber>417</OpcodeNumber>
                <OpcodeMode>0</OpcodeMode>

                <OpcodeParamsList>
                    <OpcodeParamName>PIN_FLD_POID</OpcodeParamName>
                    <OpcodeParamValue>$SERVICE$</OpcodeParamValue>
                </OpcodeParamsList>
                <OpcodeParamsList>
                    <OpcodeParamName>PIN_FLD_PROVISIONING_TAG</OpcodeParamName>
                    <OpcodeParamValue>$PROVTAG$</OpcodeParamValue>
                </OpcodeParamsList>
            </OpcodeList>

            <OpcodeList>
                <OpcodeName>PCM_OP_SUBSCRIPTION_POL_CANCEL_PROD_PROVISIONING</OpcodeName>
                <OpcodeNumber>418</OpcodeNumber>
                <OpcodeMode>1</OpcodeMode>

                <OpcodeParamsList>
                    <OpcodeParamName>PIN_FLD_POID</OpcodeParamName>
                    <OpcodeParamValue>$SERVICE$</OpcodeParamValue>
                </OpcodeParamsList>
                <OpcodeParamsList>
                    <OpcodeParamName>PIN_FLD_PROVISIONING_TAG</OpcodeParamName>
                    <OpcodeParamValue>$PROVTAG$</OpcodeParamValue>
                </OpcodeParamsList>
            </OpcodeList>

        </ProvisioningTag>

    </ProvisioningTagList>
    </ProvisioningTagConfiguration>

</BusinessConfiguration>