Agreements

An Agreement is a B2Bi object that you use to specify how B2Bi processes the information that is exchanged between two or more participants (partners or communitites).  Each agreement is based on a standards-based type of processing for X12, EDIFACT, etc.

B2Bi uses agreements at runtime to match the messages it handles to trading participants and processing.

An agreement defines one of two types of trading exchanges:

  • Inbound - Defining the characteristics of an exchange from a remote partner.
  • Outbound - Defining the enveloping required for sending to a remote partner.

Agreements may define the participants of exchanges in several ways:

  • Explicit sender/receiver relationship - Only a specific messaging identifier for a partner or community is valid.
  • Implicit sender/receiver relationship - Any messaging identifier for a partner or community is valid.
  • Semi-anonymous - Either the sender or the receiver is undefined.
  • Fully-anonymous sender and receiver relationship - Both trading participants are undefined.

To view, add and manage agreements in the B2Bi user interface, select Processing configuration > Management agreements to open the Agreements page.

When adding agreements from the B2Bi user interface, a wizard helps you select from among available participants (partners or communities) and messaging IDs to match them to a defined agreement exchange type. Accessing this information from a REST API may require accessing multiple objects and retrieving different IDs. Some of the objects include agreement type (inbound or outbound), document format, and sending and receiving partners or community.

A Document Agreement is an object that you use to specify how a document type (within a messaging standard and a standard version) is to be handled in an inbound agreement between exchange points.

For more information about agreements and document agreements, see the B2Bi Administrator Guide.

Agreement planning

An agreement is used to specify how B2Bi processes the information exchanged between two or more trading participants (partners or communities). Each agreement is based on a standards-based type of processing for X12, EDIFACT,etc. B2Bi uses agreements at runtime to match the messages it handles to participants and processing.

The trading engine service APIs support a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations. For detailed documentation on each resource and its parameters, see the dynamically generated API documentation available on your host: http://<host>:<port>/apidocs.

As you develop your agreements project plan, be sure to:

  • Read the dynamic API documentation thoroughly. Note, different methods (GET, POST, UPDATE/PUT, DELETE) apply for each sub-resource.
  • Evaluate all resources and sub-resources carefully and test in a sandbox environment.
  • Consider consulting with Axway Professional Services.

The B2Bi objects currently supported by the AgreementResource include:

  • Document agreements
  • Agreement attributes
  • Functional groups (e.g., X12 and EDIFACT)
  • Sequence numbers
  • Templates
  • Outputs
Note   You must log in to B2Bi using a valid username and password before calling other resources.

RESTQL queries

B2Bi trading engine support for RESTQL (REST Query Language) is modeled after Apigee’s query syntax. For more information, see http://apigee.com/docs/app-services/content/querying-your-data and RESTQL.

Add and configure an agreement

  1. Login. Authenticate yourself with a valid username and password combination. This will allow you to interact with the system and continue with the next steps. Depending on the tool used, authentication might be needed only once per session.
  2. Retrieve a list of available agreements with GET: /rest/v1/agreements.
  3. Add a new agreement with POST: /rest/v1/agreements. To create a new agreement object, the integration engine must be running. Agreements may be configured differently depending on the standard and trading exchange types.
  4. Configure or update the agreement with PUT: /rest/v1/agreements. Update the configuration of a specific agreement.

Configure agreement attributes

  1. Retrieve an agreement with GET: /rest/v1/agreements/<id>, where the "id" is the identifier of the agreement.
  2. Retrieve a list of agreement attributes and their values with GET: /rest/v1/agreements/<id>/attributes, where the "id" is the agreement identifier. Attributes are metadata used by the integration engine and are structured in pairs. An attribute is comprised of a name and either an associated value or a list of values.
  3. Update an agreement's attribute values with PUT: /rest/v1/agreements/<id>/attributes, where the "id" is the agreement identifier. To set a value, the attribute must be defined in the agreement attributes template.

Add a document agreement to an agreement

A document agreement is a B2Bi object used to specify how a document type - within a messaging standard and a standard version - is to be handled in an inbound agreement between exchange partners. A service can be added to define how the document will be processed. For a service to be associated with a document agreement, additional criteria may be needed.

  1. Retrieve a list of document agreement objects for a specific agreement with GET: /rest/v1/agreements/<id>/documentAgreements, where the "id" is the identifier of the agreement.
  2. Add a document agreement to an agreement with POST: /rest/v1/agreements/<id>/documentAgreements, where the "id" is the identifier of the agreement.

Add a functional group to an agreement

When one or more transaction sets are received from a trading partner in a message exchange, the transaction sets will be grouped in functional groups within the envelope. Transaction sets that are grouped together are identified by the same functional group ID. The agreements that support functional grouping are X12 and EDIFACT.

  1. Retrieve a list of functional groups for a specific agreement with GET: /rest/v1/agreements/<id>/functionalGroups, where the "id" is the identifier of the agreement.
  2. Add a functional group to an agreement with POST: /rest/v1/agreements/<id>/documentAgreements, where the "id" is the identifier of the agreement.

Add an attribute to the agreement attributes template

  1. Retrieve a list of attributes associated with the agreement attributes template with GET: /rest/v1/agreements/attributes/templates.
  2. Add a new attribute to the agreement attributes template with POST: /rest/v1/agreements/attributes/templates. For a single-selection or multi-selection attribute, you can define a list of possible values. Make the attribute required if it is to be included on all exchanges.
  3. Configure an attribute added to the agreement attributes template with PUT: /rest/v1/agreements/attributes/templates. An attribute is marked as required makes the agreement incomplete if no value is provided.

Update attribute values for a document agreement

  1. Retrieve a list of attributes and their values for a specific document agreement with GET: /rest/v1/agreements/documentAgreement/<id>/attributes, where "id" is the document agreement identifier.
  2. Update attribute values for a specific document agreement with PUT: /rest/v1/agreements/documentAgreement/<id>/attributes, where "id" is the document agreement identifier.

Add an attribute to the document agreement attributes template

  1. Retrieve a list of attributes associated with the document agreement attributes template with GET: /rest/v1/documentAgreement/attributes/templates. This template is associated with all document agreements available in the system.
  2. Add a new attribute to the document agreement attributes template with POST: /rest/v1/documentAgreement/attributes/templates. For a single-selection or multi-selection attribute, you can define a list of possible values. Make the attribute required if it is to be included on all exchanges.
  3. Configure an attribute added to the document agreement attributes template with PUT: /rest/v1/documentAgreement/attributes/templates. An attribute is marked as required makes the agreement incomplete if no value is provided.

Configure a document agreement output

  1. Retrieve a list of outputs specific to a document agreement with GET: /rest/v1/documentAgreements/<id>/outputs, where "id" is the document agreement identifier. An output contains configuration parameters that specify how the document will be delivered or enveloped.
  2. Update the configuration for a specific output with PUT: /rest/v1/documentAgreements/outputs. Depending on the service type, the document agreement can have one or multiple outputs.
  3. Retrieve the configuration for a specific output with GET: /rest/v1/agreements/documentAgreements/outputs/<id>, where "id" is the output identifier.

Update the configuration of a specific functional group

  1. Update a specific functional group configuration with PUT: /rest/v1/agreements/functionalGroups.
  2. Retrieve a specific functional group with GET: /rest/v1/agreements/functionalGroups/<id>, where "id" is the functional group identifier.
  3. Remove a specific functional grouop with DELETE: /rest/v1/agreements/functionalGroups/<id>, where "id" is the functional group identifier. The default functional group of an X12 outbound agreement cannot be deleted.

Configure agreement components

Two types of outbound agreements reference a component for enveloping: XML and Inhouse. When you perform a "GET" on an agreement, the component ID appears in the URI for the enveloper within the XMLOutboundAgreementBean or the InhouseOutboundAgreementBean.

  1. Retrieve an agreement with GET: /rest/v1/agreements/<id>, where the "id" is the identifier of the agreement. If the agreement includes an enveloper, the component number is the "enveloper" value. For example, if the retrieved agreement result includes "enveloper": "/v1/agreements/component/54001", the component ID is 54001.
  2. Retrieve the component with GET: /rest/v1/agreements/component/<id>, where "id" is the component identifier retrieved in the last step.
  3. Retrieve the configuration parameters of the component with GET: /rest/v1/agreements/component/<id>/configurations, where "id" is the component identifier. The parameters can be configured to specify the component characteristics.
  4. Retrieve the specified configuration parameters with GET: /rest/v1/agreements/component/configurations/<id>, where "id" is the identifier of the configuration parameters specified in the last step.
  5. Retrieve a list of parameters grouped into categories with GET: /rest/v1/agreements/component/configurations/<id>/arguments, where "id" is the identifier used to specify the list of arguments. The configuration of parameters is grouped into different categories. To configure these parameters, you must access the list of arguments specific to a category. You can specify the input format or the output formats of the document, and provide values for specific parameters used to describe component object characteristics. The identifier is returned within the configuration bean.
  6. Set a value for a specific configuration parameter with PUT: /rest/v1/agreements/component/configurations/arguments.

Related Links