1. Implementing Buying Experience
  2. Manage Contract Templates

Manage Contract Templates

You can manage the Templates file by retrieving the details using the Template API. You can get all the available Template file details using this API.

Note: Contract templates can be stored in any document management system through the document management adapter. The CXIF document management adapter must be configured to work with the preferred document management system.

Here's how you can get the template details:

  • To get the template details , run the following cURL command or use a REST API client:
    curl -H Authorization: Bearer <accessToken> https://<hostName>/cx/industry/buying/configManagement/v1/template -X GET
  • To download one specific template file, run the following cURL command or use a REST API client:
    curl -H Authorization: Bearer <accessToken> https://<hostName>/cx/industry/buying/configManagement/v1/template/{id} -X GET

How to Upload Contract Template

A contract template is used to generate the contract for the user. You need to upload the template using the Template API. While uploading the template file, you should add metadata along with the file.

Here's how you can upload the contract template file:

  1. Create payload to upload the template with the details described. The payload is multipart:

    • First body part (template file in binary format)

      • Param Name: file
      • Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

    • Second body part (JSON Payload with MetaData )

      • Param Name: templateParameters
      • Content-Type: application/json
    • As part of templateParameters, you must add
      • name: Indicates name of the template. It is a required string attribute.
      • specificationBased: Indicates whether the template will be specification based or not. It is a required boolean attribute. Templates that support specification based placeholder mappings will have the value for this field as true. Where as, for static templates and for the generic contract templates, the specificationBased property will have the value as false.
      • contentType: Whether the content of file is Static -Doesn't contain any placeholder and should be in html format. It will be used for before checkout scenarios or Dynamic - May contain Placeholder and would be used for the actual contract generation and should be in docx format.

      • domain: Currently it can have only "Consumer", for the B2C Scenario.

      • Tags: Tags for the uploaded template file for which this template file should be used for Contract Generation. Supported tags are accountType, country, stateOrProvince.
  2. Call the Template API by running this cURL command or by using a REST API client:
     curl --location --request POST 'https://<hostname>/cx/industry/buying/configManagement/v1/template' --header 'Authorization: Bearer <Access-Token>' --form 'file=@"contractTemplate.docx"' --form 'templateParameters=@"template-request.json";type=application/json'

Where:

  • <accessToken> is the OAuth access token for Contract Administrator Role.

  • <hostName> is the URL for the CX Industries Framework API Gateway.

Update Contract Template

You can update the already uploaded template file and the associated metadata with the file.

To update the contract, call the Template API by running this cURL command or by using a REST API client:

curl --location --request PATCH 'https://<hostname>/cx/industry/buying/configManagement/v1/template' --header 'Authorization: Bearer <Access-Token>' --form 'file=@"contractTemplate.docx"' --form 'templateParameters=@"template-request.json";type=application/json'

Where:

  • <accessToken> is the OAuth access token for Contract Administrator Role.
  • <hostName> is the URL for the CX Industries Framework API Gateway.

Key Points to Consider for a Contract Template

  1. Templates of type DOCX are only accepted.
  2. Templates should have a placeholder defined as ${placeholder_name} for replacement with actual data. For example ${Account_Name}
  3. The table that mentions the terms and conditions of the different product offers that are part of the contract is called the Service Agreement Details table, which should have a header row and a data row with the required placeholder for each column's data that are dynamically expanded. The Templates can only have placeholder names from the below list, for the Service Agreement Details table that can also be fetched using the following URL: 
    curl -H Authorization: Bearer <accessToken>
      https://<hostName>/cx/industry/buying/configManagement/v1/mappings -X GET
    and thereafter looking at "tmfSpec.id" field for value "TMF651".
    Placeholder Name TMF Spec ID reference field path in Payload
    ProductOffering_Name 651 agreementItem.productOffering.name
    Agreement_StartDate 651 agreementPeriod.startDateTime
    Agreement_EndDate 651 agreementPeriod.endDateTime
    OwnerAccount_Name 651 ownerAccount.name
    Term_Start_Date_Time 651 agreementItem.termOrCondition.validFor.startDateTime
    Term_End_Date_Time 651 agreementItem.termOrCondition.validFor.endDateTime
    Agreement_Name 651 name
  4. You should specify the table caption "SERVICE AGREEMENT DETAILS" as table alternative text using MS Word's table properties.
  5. The attributes mentioned in the Service agreement details table are mandatory for any contract template and are not configurable.
  6. If any part of the template has content in a table format without a border, when this template is used to generate the contract in PDF, the system applies an outline border in the final PDF document.
  7. We are not supporting text box for a DOCX template.
  8. DOCX template with the image as bullet point doesn't keep the image. Icons in bullet points are converted to simple bullet points.
For more information on using the contract templates, refer to the sample contract template provided in the support article for Buying Experience (2730574.1) on My Oracle Support at https://support.oracle.com.

Manage Generic Contract Templates

Generic contract templates are independent of placeholder mappings, allowing the use of any placeholder in the template. While using these templates to generate a contract, you must provide values for the defined placeholders within the template.

You can include a placeholder of the name 'ContractNumber' in the template header. The system will automatically generate the contract number and replace this placeholder, eliminating the need to provide this value in the JSON payload request. Also, if you prefer, you can place this placeholder in the footer or body of the template. 'ContractNumber' is a reserved placeholder, indicating that even if the caller provides a value for this placeholder, it can always be overridden with the generated value.