Using the Serial Number Assignment Service

The following sections describe how to configure the Serial Number Assignment Service and use the Serial Number Assignment Console.

Overview of the Serial Number Assignment Service

The Serial Number Assignment Service provides centralized management for allocating (or provisioning) blocks of EPCs to tag writing systems running in remote facilities. In many cases it is desirable for a tag writing system to write tags using a set of EPCs maintained locally, but replenished from a central repository as more EPCs are needed. These use cases are handled through the use of EPC caches (collections of EPC values). The Serial Number Assignment Service replenishes the EPC caches maintained by tag writing systems when requested to do so. By maintaining pools of EPCs in a central location, the likelihood of duplicate or misallocated EPC blocks is reduced.

EPC allocation for all your tag writing systems is accomplished by connecting to the Serial Number Assignment Console, a Web interface to create selection rules and monitor EPC pools, as well as an API to check in and check out EPCs, and database tables for data persistence.

Typically, an organization deploying the Serial Number Assignment Service already has one or more tag writing systems that require access to a cache of EPCs. You configure the Serial Number Assignment Service by:

Setting up serial number selection rules using the Serial Number Assignment Console. See Creating Selection Rules.
Establishing communication between the Serial Number Assignment Service component and the tag writing systems in use at your organization. This is usually a two-step process:

Configure individual tag writing systems to communicate with the Serial Number Assignment Service (thereby transforming them into EPC Clients).
Use the Serial Number Assignment Service API to write code that communicates with the Serial Number Assignment Service to check out and check in EPCs for a given EPC Client. See Using the Serial Number Assignment Service API.

Note that this step is not necessary if your organization uses the Serial Number Assignment Service to communicate with other BEA RFID software such as Compliance Express.

Once your systems have been integrated with the Serial Number Assignment Service, we recommend monitoring all pools for current usage and potential depletion. See Monitoring Pools.

Creating Selection Rules

The Serial Number Assignment Service can allocate two types of EPCs: SGTIN and SSCC. (For more information on EPC tag formats, see the EPCglobal Tag Data Standards Version 1.1). The type of EPC allocated depends on the identifier provided by the requesting program (also known as an EPC Client). GTINs are provided to the EPC Client when it requests replenishment for a cache of SGTINs. In this case, the Serial Number Assignment Service serializes the GTINs to produce SGTIN EPCs. A similar operation occurs when the EPC Client requests replenishment for a cache of SSCCs; the EPC Client provides a company prefix value, which is serialized to produce SSCC EPCs. All the available EPCs for a given GTIN or company prefix are called (collectively) a pool.

In addition to a GTIN or company prefix, the EPC Client also provides a set of criteria to the Serial Number Assignment Service, which uses this information to determine which EPCs will be returned. It does this by matching the criteria received from the EPC Client against the existing selection rules. A selection rule is made up of user-defined criteria that define a subset of a pool. If the criteria specified by the EPC Client match the criteria from the selection rule, and it is the first matching selection rule, EPCs from that subset of the pool will be returned to the EPC Client. The checked-out EPCs are cached by the EPC Client and are then available for writing to tags.

Selecting the serial number range within a pool from which EPCs are chosen when responding to a request from an EPC Client.
Defining subsets of a pool to provide EPCs to various EPC Clients in accordance with business requirements in place at the organization using the Serial Number Assignment Service. For example, if your organization has more than one shipping area, you may want to define selection rules to provide each area with distinct sets of EPCs.

Figure 2-1 illustrates the relationship between selection rules and EPC pools.

Figure 2-1 Selection Rules and Pools

Selection Rules and Pools

When creating selection rules, you must consider which areas or business units will be requesting EPCs. How many are there? Will each area require separate serial number ranges? Does your corporate data center have any requirements regarding EPC ranges? Is there business logic that needs to be taken into account in making selection rules? By considering these factors, you will be able to set up selection rules that will create EPC pools of adequate size, containing EPCs that provide useful business information to your organization's enterprise systems.

Use the Serial Number Assignment Console, accessible via a Web browser, to create and manage selection rules.

Start a Web browser and navigate to the login page for the Serial Number Assignment Console, substituting the machine's hostname for hostname in the URL: http://<hostname>:<wls_port>/epcps_webclient

Alternatively, from the login page of the RFID Enterprise Server Console (http://<hostname>:<wls_port>/enterprise), select Serial Number Assignment Service.

On the Serial Number Selection Rules page, click Add.

The Add Serial Number Selection Rule page displays, shown in Figure 2-2.

Figure 2-2 Add Serial Number Selection Rule

Add Serial Number Selection Rule

Define a selection rule by filling in the Selection Rule fields, described in Table 2-1.

Name

Description

Identity Type

The type of EPC affected by this rule.

Tag Length

The type of tag affected by this rule (96 bits, 64 bits, or Unspecified). Contains the length (in bits) of the EPCs to be allocated by the Serial Number Assignment Service.

Range

The range of serial numbers affected by this rule. You can specify the range by start and end numbers, by number of EPCs needed, or by using the maximum range possible. After making your choice from the drop-down list, fill in the range fields.

Criteria

The types of criteria (in Name/Value pairs) entered for a rule depend on the needs of the business unit using the Serial Number Assignment Service. You can use criteria to identify a tagging station, a work unit, a specific GTIN or company prefix, or an area of a warehouse, among other things. Use the Add button to add more criteria to the list, if necessary.

Note: The term TAG_LENGTH is used internally by the Serial Number Assignment Console, and should not be part of any criteria entered into the system.

Click Save to save the selection rule.
Select the Serial Number Selection Rules tab to return to the Serial Number Selection Rules page where you use the controls in the Action column to modify rule positions and edit or delete rules.

Use the Up and Down buttons to put rules in the order you prefer. The order that rules are in matters; a checkout request will use the first rule from the list that matches. Put more specific rules first, and more general rules at the end of the list. If a more general rule is positioned at the start of the list, it will be used in preference to a more specific rule later in the list.
To edit a rule, click the Edit button next to the rule.
To delete a rule, click the Delete button next to the rule.

Integrating with Tag Writing Systems

This section provides details required for developers writing programs that integrate the Serial Number Assignment Service with existing tag writing systems. To get started, choose one of the following integration scenarios. For scenarios 1 and 3, development can use any language that supports classes; this document describes Java classes.

If your organization has WebLogic RFID Edge Server 2.0 or later:

Set up the RFID Edge Server to send an EPCCacheReport (essentially a replenishment request) when the tag cache is running low. Use the Serial Number Assignment Service WSDL interface to develop program(s) that receive and act on the EPCCacheReport, and use ALEPC API calls to replenish the cache. See WebLogic RFID Edge Server for more information.

If the organization has other RFID software (Compliance Express, for example):

Configure the software to interact with the Serial Number Assignment Service. See Compliance Express for more information.

If your organization has its own tag writing system:

Use the Serial Number Assignment Service WSDL interface to develop programs that detect when the cache of EPCs kept by a tag writing system is about to be depleted, use the Serial Number Assignment Service API to check in and check out EPCs as needed, and return those EPCs to the tag writing system to replenish its EPC cache. See Using the Serial Number Assignment Service API.

Compliance Express

To integrate the Serial Number Assignment Service with Compliance Express, uncomment and set values for the following properties in the COMPLIANCE_HOME\etc\tagging-station.props file. Your changes will take effect after you restart Compliance Express.

The serviceURL and notificationURI properties give information about how to contact the Serial Number Assignment Service.

com.connecterra.compliance.epcps.serviceURL= http://<Serial_Number_Assignment_Service_host>:<wls_port>/epcprovisioning/EPCProvisioningService

com.connecterra.compliance.epcps.notificationURI= jms:///queue/weblogic.jms.ConnectionFactory/epcpsBrokerMessages

The namingPropertiesFile property identifies the location of a naming.props file for the JMS connection to the Serial Number Assignment Service.

com.connecterra.compliance.notificationDriver.jms.default.namingPropertiesFile=naming.props

The file name may include either an absolute path or a path relative to the location of tagging-station.props. See naming.props in Installing WebLogic RFID Edge Server for more information on specifying and using the naming.props file.

The cacheSize property specifies the number of EPCs to check out and add to the cache.

com.connecterra.compliance.epcps.cacheSize=1000

The cacheLowThreshold property specifies when a cache should be refilled. When the number of EPCs in the cache reaches this value, a cache low notification will be sent so the cache can be replenished.

com.connecterra.compliance.epcps.cacheLowThreshold=10

The userParameter property specifies a user-defined parameter and value to be sent with EPC checkout requests. There can be multiple parameters specified. These parameters match criteria set in the selection rules.

#com.connecterra.compliance.epcps.userParameter.<parameter1>.value=<value1> com.connecterra.compliance.epcps.userParameter.Shift.value=Morning

By default, Compliance Express sends EPC checkout requests with the following parameters: GTIN=<value>, TAG_LENGTH=<value>, FILTER_BIT=<value>, and LOCATION_ID=<value>. You should not specify these parameters as user parameters.

WebLogic RFID Edge Server

In the WebLogic RFID Edge Server, one or more PCSpec instances may be associated with an EPC cache.The RFID Edge Server maintains the defined PCSpec instances and their EPC caches as part of its persistent state. Each time a PCSpec is activated, it takes the next EPC value from its EPC cache, and attempts to write that to a tag. When multiple PCSpec instances share a single cache, each will get a different EPC value each time it is activated. The RFID Edge Server tag programming facility can issue a cache report (called EPCCacheReport) when the number of remaining EPC values in a cache drops to (or below) a specified level. These reports are essentially replenishment requests for the cache.

For information on EPC caches, see Reading and Writing Tags in Programming with the ALE and ALEPC APIs.

To integrate the Serial Number Assignment Service with systems running the RFID Edge Server, you will need to:

Set up subscribers for EPCCacheReports in the RFID Edge Server. The Edge Server sends these reports when it detects that the tag cache currently being used to print tags is running low.

See Creating and Removing Subscribers in Using the Administration Console. JMS and HTTP notification driver configuration is described in Configuring WebLogic RFID Edge Server in Installing WebLogic RFID Edge Server.

Write code to detect the receipt of an EPCCacheReport.
Use the WSDL interface included with the Serial Number Assignment Service to validate and submit an EPC checkout request to the Serial Number Assignment Service. The public API is described in Using the Serial Number Assignment Service API.
Use ALEPC API calls to replenish the EPC cache on the Edge Server using the EPCs returned by the Serial Number Assignment Service. See Programming with the ALE and ALEPC APIs for more information.

EPCCacheReport

A report sent by the RFID Edge Server that indicates that an EPC cache needs replenishing.

Field	Description
`applicationData`	String that you set in the `EPCCacheSpec`. See Writing Tags by Using the ALEPC API for more information.
`cacheContent`	Describes the remaining content of the EPC cache.
`cacheName`	The name of the EPC cache that this report describes.
`cacheSize`	How many EPC cache entries remain.
`date`	The time the report was generated.
`savantID`	Identifier for the Edge Server that generated this report.
`threshold`	The low-cache reporting threshold defined for the EPCCacheSpec.

Using the Serial Number Assignment Service API

The methods described in this section make up the public API for the Serial Number Assignment Service.

EPC Identity Patterns

The Serial Number Assignment Service uses EPC identity patterns to specify sets of EPCs that will be checked out (or checked in, in the case of checkin operations). An EPC identity pattern is a URI-formatted string that denotes a single EPC or set of EPCs. The format will be one of:

The fields CompanyPrefix, ItemReference, SerialNumber, and SerialReference correspond to fields of an EPC. In an EPC ID pattern returned from the Serial Number Assignment Service, the SerialNumber and SerialReference fields may be:

An integer, meaning that a matching EPC must have that specific value in the corresponding field; or
A range denoted like [lo-hi], meaning that a matching EPC must have a value between the decimal integers lo and hi, inclusive.

Here are some examples of EPC ID patterns returned by the Serial Number Assignment Service. In these examples, assume that 0614141 is the Company Prefix for Widget Corporation, and 100734 is the Item Reference for its UltraWidget product, and that SGTIN tag encodings are used.

Pattern URNs	Description
`urn:epc:idpat:sgtin:0614141.100734.4000`	Matches the tag for UltraWidget serial number 4000.
`urn:epc:idpat:sgtin:0614141.100734.[100-999]`	Matches any Widget Corporation product whose serial number is between 100 and 999, inclusive.

If, for example, the second EPC ID pattern shown above were checked out and the tag length and filter value (96:0) were added, the resulting cache contents would be urn:epc:pat:sgtin-96:0.0614141.100734.[100-999].

A cache contains an ordered list of EPC patterns, each of which represents a range of EPC values ordered by ascending serial number; the EPC cache content is the concatenation of the ranges corresponding to pattern URNs in the list.

checkin

The checkin() call takes one argument—a list of EPC ID patterns in a StringList object. If the checkin() call succeeds, the EPC ID patterns are checked in.

A checkin() call may throw any of the following exceptions: ServiceException, ProvisioningException, InvalidURIException, or RemoteException.

checkout

The checkout() call takes four arguments, which are explained in the table below:

Argument	Description
Checkout Parameters	An `EPCRequestCriteria` object, which consists of: an EPC identity type (`SGTIN` or `SSCC`) an internal criteria name/value pair, which is `GTIN=<value>` (for an `SGTIN` identity type) or `COMPANY_PREFIX=<value>` (for an `SSCC` identity type) any user-specified criteria name/value pairs (which may be from the selection rule used)
Chunk Size	The number of EPCs that the method should return.
Requestor ID	An identifier for the user or service requesting the checkout.
Allow Smaller Chunks?	A boolean, indicating whether the chunk size can be satisfied by returning EPC ID patterns representing non-contiguous blocks of EPCs.

If the checkout() call succeeds, the EPC ID patterns are checked out and returned to the calling program as a StringList.

A checkout() call may throw any of the following exceptions: ServiceException, PoolLowException, ProvisioningException, or RequestDeniedException.

validateEPCRequest

This method checks the validity of a potential checkout() request. It checks for a selection rule that satisfies the request, and looks for a GTIN or Company Prefix in the EPCRequestCriteria object that is passed in. (See checkout for a description of the EPCRequestCriteria object.)

If the validateEPCRequest() call succeeds, it returns the string representation of the rule that satisfies the request.

A validateEPCRequest() call may throw any of the following exceptions: ServiceException, ProvisioningException, or RequestDeniedException.

Example Checkout Request

The example in Figure 2-4 shows a checkout() request being issued for a particular pool, and a block of checked-out EPCs being returned to the requesting system.

Monitoring Pools

Once your systems have been integrated with the Serial Number Assignment Service, we recommend monitoring all pools for current usage and potential depletion. Use the Serial Number Assignment Console, accessible via a Web browser, to perform these monitoring activities.

Start a Web browser, and navigate to the login page for the Serial Number Assignment Console, substituting the machine's hostname for hostname in the URL: http://<hostname>:<wls_port>/epcps_webclient

Alternatively, from the login page of the RFID Enterprise Server Console (http://<hostname>:<wls_port>/enterprise), select Serial Number Assignment Service.

Select the Pools tab.

A list of pools displays. From this page you can monitor all pools in use.

Figure 2-5 Pools Tab

Pools Tab

Click the Pool Key link to view pool usage.

The Pool Usage page displays.

A list of checkout times and ranges displays. From this page you can monitor the usage of the pool you chose.

Figure 2-6 Pool Usage

Pool Usage

Click the Back to Pools Page button to return to the original list of pools.