Create a contract with data fields

Data fields are simply put contract variables. Using data fields, it is possible to send in any text data into a contract and use them in either text and image sections or product descriptions. You can set the data field values either on contract creation or by updating them later.

The data fields are inherited from the template, which in turn gets them from a template type. Only data fields inherited this way can be set.

Step 1. Create a template type with data fields

To create a template type, you first have to enable the Template types extension.

  1. Go to the Oneflow application Admin > Account > Extensions tab, and toggle the Template types extension.

🚧

Note:

In the current version of Oneflow, the extension is labeled as Template groups and will be renamed to Template types in future versions.

You can now create a new template type and add data fields to it. You can see the detailed instructions here.

Once created, you can select the new template type in your template.

Step 2. Obtain necessary information

To run the script described in this tutorial, you’ll need the following data:

Headers
x-oneflow-api-token You will only be able to run the script by using a valid API token. You can create an API token in the Oneflow web application. Find more in the Authentication section.
x-oneflow-user-email Your Oneflow user account email. You can find all user-related information using the users endpoint.
Body
workspace_id The unique ID of the workspace where you want to create your contract. You can find the workspace ID using the workspaces endpoint.
template_id The unique ID of the template you want to use for creating your contract. You can find the template ID using the templates endpoint.
Data fields
data_fields The data_fields attribute is an array of data field objects. Each of these data field objects has two required attributes: custom_id and value.
custom_id The unique name that was given to the data field when it was added to the template type.
value The value that will be displayed in the contract for the data field.

Step 3. Run the code

🚧

Note

  • The value parameter can contain a maximum of 1024 characters.

Replace the values of the parameters in the following command with the actual data from your account:

curl --request POST \
  --url https://api.oneflow.com/v1/contracts/create \
  --header 'content-type: application/json' \
  --header 'x-oneflow-api-token: API_TOKEN' \
  --header 'x-oneflow-user-email: USER_EMAIL' \
  --data '{"workspace_id": WORKSPACE_ID,"template_id": TEMPLATE_ID, "data_fields": [{"custom_id": "first_name", "value": "Bob"},{"custom_id": "last_name", "value": "Ross"}]}'
import requests

headers = {
    'content-type': 'application/json',
    'x-oneflow-api-token': 'API_TOKEN',
    'x-oneflow-user-email': 'USER_EMAIL',
}

data = {
  "workspace_id": WORKSPACE_ID,
  "template_id": TEMPLATE_ID, 
  "data_fields": [
    {
      "custom_id": "first_name", 
      "value": "Bob"
    },
    {
      "custom_id": "last_name", 
      "value": "Ross"
    }
  ]
}

response = requests.post('https://api.oneflow.com/v1/contracts/create', 
                         headers=headers, json=data)

print(reponse.json())

When setting data fields in the create contract request, you can expect the following behavior:

Data field is in requestData field is in template typeResult
The value of the data field in the request will override the value of the template type and display it in the contract.
An error will occur, and the contract will not be created.
The value from the template type will be displayed in the contract unchanged.

When setting data fields in a template type, you can expect the following behavior:

Data field is in requestData field is in template typeResult
The value of the data field in the request will override the value of the template type and display it in the contract.
The data field will be created in the template type.
The data field will be removed from the template type.

❗️

Warning:

Be careful when customizing data fields at the template type level, as you could accidentally remove them from the template type.

Expected response

This request will output details about the contract with the data fields you created in the JSON format. The output will be similar to the output of the Create contract request.

Please see the Data field section in the Data model category for more information about the output.

Response codes

StatusMeaningDescription
200OKReturns the created contract.
400Bad RequestInvalid format or content of the request.
404Not FoundA required entity is missing.
409ConflictA conflict occurred with the current state of the target resource.