Create dynamic fields (x-ntx-dynamic-schema)
|
In this example, you will add the x-ntx-dynamic-schema Specification Extension A Nintex-specific OpenAPI Specification key that allows special functionality within Nintex Xtensions. to dynamically generate the list columns of a SharePoint list in the action's configuration fields. For a reference on this specification extension, see x-ntx-dynamic-schema. Note: Nintex Automation Cloud provides SharePoint Online actions out-of-the-box. This example is provided only as a guide to creating dynamic parameters, and will not function as an Xtension. For more information on this specification extension, see our full guide: x-ntx-dynamic-schema. |
Some operations A single request to a third-party API. Operations often become actions in the workflow designer. might require different parameters A piece of information passed to a third-party API during a request. each time they're used. For example, a workflow action that adds data to a SharePoint list will need configuration fields that match the list's structure. We could hard-code the list's parameters into the operation definition, but then we could only ever use that action with a list that matched that structure. To create an operation that could be used with any SharePoint list, we use x-ntx-dynamic-schema to dynamically request the operation's parameters via the API.
Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.
Looking for other examples?
The following examples also use x-ntx-dynamic-schema:
Also see the how-to on x-ntx-dynamic-schema.
Dynamic-schema
The x-ntx-dynamic-schema Specification Extension is added to an object definition in place of the properties object, to tell Nintex Automation Cloud that this object is dynamically defined by the API at runtime. Inside the x-ntx-dynamic-schema object, you define:
- Which 'helper' operation provides the data structure for the dynamic object.
- The path in the response The return from a third-party API after a request has been made by the client. object that defines the object's structure.
- What parameters to pass to the helper operation, if any.
Note: To be able to use x-ntx-dynamic-schema, the API you use must provide an endpoint that returns a description of the object's data structure.
Nintex Xtensions also supports the Microsoft Flow format of this Specification Extension: x-ms-dynamic-schema.
Create the Xtension
Step 1: Create the basic OpenAPI Specification
Create an OpenAPI Specification that:
- Uses your SharePoint site as a host The domain name of the third-party API's URL..
- Uses OAuth2 authentication with two scopes to modify and read sites.
- Defines an operation /ListItemCreate to create a list item in a SharePoint list that uses two helper operations with x-ntx-dynamic-values:
- An operation /GetSites to retrieve the available sites for the SharePoint URL.
- An operation /GetLists/List to retrieve the available lists from the SharePoint site.
For more information on using x-ntx-dynamic-values, see x-ntx-dynamic-values.
- Defines a set of data structures for Sites, Lists, and an empty structure for items to create (ItemCreate).
For more information on creating definitions, see Streamline with references.
Note: If additionalProperties is not defined for an object, it defaults to true, allowing workflow designers to add arbitrary properties to that object.
For more information on using OAuth2 authentication, see OAuth 2.0 authentication.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "SharePoint Online",
"description": "A sample Xtension"
},
"host": "SHAREPOINTSITE.azurewebsites.net",
"basePath": "/api",
"schemes": [ "https" ],
"produces": [ "application/json" ],
"paths": {
"/ListItemCreate": {
"post": {
"tags": [
"List item",
"Create"
],
"summary": "Create an item",
"description": "Create an item",
"operationId": "ListItemCreate",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetSites",
"value-path": "Url",
"value-title": "Url"
}
},
{
"name": "listName",
"in": "query",
"description": "List name",
"required": true,
"x-ntx-summary": "List name",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetListsList",
"parameters": {
"siteUrl": {
"parameter": "siteUrl"
}
},
"value-path": "Name",
"value-title": "Name"
}
},
{
"name": "folderPath",
"in": "query",
"description": "Folder path",
"required": false,
"x-ntx-summary": "Folder path",
"type": "string"
},
{
"name": "fields",
"in": "body",
"description": "Add fields",
"required": true,
"schema": {
"$ref": "#/definitions/ItemCreate"
},
"x-ntx-summary": "Add fields"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"Id": {
"title": "Store item ID",
"type": "integer",
"format": "int64",
"description": "ID of the list item"
},
"Url": {
"title": "Store item URL",
"type": "string",
"description": "URL of the list item"
}
}
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
},
"/GetSites": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Sites" ],
"summary": "Get sites",
"description": "Get sites",
"operationId": "GetSites",
"produces": [ "application/json" ],
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Sites"
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
},
"/GetLists/List": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Lists" ],
"summary": "Get lists",
"description": "Get lists",
"operationId": "GetListsList",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Lists"
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
}
},
"definitions": {
"Sites": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"Id": {
"type": "string"
},
"Title": {
"type": "string"
},
"Url": {
"type": "string"
}
}
}
},
"Lists": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"Id": {
"type": "string"
},
"Name": {
"type": "string"
}
}
}
},
"ItemCreate": {
"type": "object",
"additionalProperties": false
}
},
"securityDefinitions": {
"functions_auth": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://api.example.com/oauth2/authorize",
"tokenUrl": "https://api.example.com/oauth2/token",
"scopes": {
"Sites.ReadWrite.All": "modify sites",
"Sites.Read.All": "read sites"
"offline access" : "Access to resource on behalf of the user for an extended time"
}
}
}
}
Step 2: Add the helper operation to retrieve the schema
Add the GetFields/Create operation, which will retrieve the data structure for creating an item in a list. Use:
- x-ntx-dynamic-values to retrieve the SharePoint site URL and the list name from GetSites and GetLists/Lists.
For more information on using x-ntx-dynamic-values, see x-ntx-dynamic-values. - x-ntx-visibility to hide this helper operation from the workflow designer.
For more information on using x-ntx-visibility, see x-ntx-visibility.
In the responses object, define the 200 response with an object that uses the ItemCreate definition.
"/GetFields/Create": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Fields" ],
"summary": "Get fields",
"description": "Get fields",
"operationId": "GetFieldsCreate",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetSites",
"value-path": "Url",
"value-title": "Url"
}
},
{
"name": "listName",
"in": "query",
"description": "List name",
"required": true,
"x-ntx-summary": "List name",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"items": {
"$ref": "#/definitions/ItemCreate"
}
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
}
Step 3: Add dynamic-schema to the ItemCreate parameter object definition
In the ItemCreate object definition, add the x-ntx-dynamic-schema object, with:
- The operationID of the GetFields/Create helper operation.
See operationId in the x-ntx-dynamic-schema guide. - The value-path of Schema/Items.
See value-path in the x-ntx-dynamic-schema guide.
"ItemCreate": {
"type": "object",
"additionalProperties": false,
"x-ntx-dynamic-schema": {
"operationId": "GetFieldsCreate",
"value-path": "Schema/Items"
}
}
Step 4: Add the required parameters to the dynamic-schema definition
The /GetFields/Create operation requires two parameters: the SharePoint site url and the list. To pass these parameters to the helper operation, define them inside the x-ntx-dynamic-schema object:
- Add a parameters object to thex-ntx-dynamic-schema object.
- Inside the parameters object, define each parameter you need to pass, using the name of the parameter as it is defined in the helper operation as the key, and either:
- A static value to pass as the parameter. For example: "listName" : "My list".
- An object to pass a dynamic value. Use a key of parameter and a value of the parameter name.
See parameters in the x-ntx-dynamic-schema guide.
"ItemCreate": {
"type": "object",
"additionalProperties": false,
"x-ntx-dynamic-schema": {
"operationId": "GetFieldsCreate",
"parameters": {
"siteUrl": {
"parameter": "siteUrl"
},
"listName": {
"parameter": "listName"
}
},
"value-path": "Schema/Items"
}
}
The OpenAPI Specification
The complete OpenAPI Specification is below.
Note: Nintex Automation Cloud provides SharePoint Online actions out-of-the-box. This example is provided only as a guide to creating dynamic parameters, and will not function as an Xtension.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "SharePoint Online",
"description": "A sample Xtension",
},
"host": "SHAREPOINTSITE.azurewebsites.net",
"basePath": "/api",
"schemes": [ "https" ],
"produces": [ "application/json" ],
"paths": {
"/ListItemCreate": {
"post": {
"tags": [
"List item",
"Create"
],
"summary": "Create an item",
"description": "Create an item",
"operationId": "ListItemCreate",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetSites",
"value-path": "Url",
"value-title": "Url"
}
},
{
"name": "listName",
"in": "query",
"description": "List name",
"required": true,
"x-ntx-summary": "List name",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetListsList",
"parameters": {
"siteUrl": {
"parameter": "siteUrl"
}
},
"value-path": "Name",
"value-title": "Name"
}
},
{
"name": "folderPath",
"in": "query",
"description": "Folder path",
"required": false,
"x-ntx-summary": "Folder path",
"type": "string"
},
{
"name": "fields",
"in": "body",
"description": "Add fields",
"required": true,
"schema": {
"$ref": "#/definitions/ItemCreate"
},
"x-ntx-summary": "Add fields"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"Id": {
"title": "Store item ID",
"type": "integer",
"format": "int64",
"description": "ID of the list item"
},
"Url": {
"title": "Store item URL",
"type": "string",
"description": "URL of the list item"
}
}
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
},
"/GetSites": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Sites" ],
"summary": "Get sites",
"description": "Get sites",
"operationId": "GetSites",
"produces": [ "application/json" ],
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Sites"
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
},
"/GetLists/List": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Lists" ],
"summary": "Get lists",
"description": "Get lists",
"operationId": "GetListsList",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Lists"
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
},
"/GetFields/Create": {
"get": {
"x-ntx-visibility": "internal",
"tags": [ "Helper", "Fields" ],
"summary": "Get fields",
"description": "Get fields",
"operationId": "GetFieldsCreate",
"produces": [ "application/json" ],
"parameters": [
{
"name": "siteUrl",
"in": "query",
"description": "SharePoint site URL",
"required": true,
"x-ntx-summary": "SharePoint site URL",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "GetSites",
"value-path": "Url",
"value-title": "Url"
}
},
{
"name": "listName",
"in": "query",
"description": "List name",
"required": true,
"x-ntx-summary": "List name",
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"items": {
"$ref": "#/definitions/ItemCreate"
}
}
},
"default": {
"description": "Operation Failed"
}
},
"security": [
{
"functions_auth": [
"Sites.ReadWrite.All",
"Sites.Read.All"
]
}
]
}
}
},
"definitions": {
"Sites": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"Id": {
"type": "string"
},
"Title": {
"type": "string"
},
"Url": {
"type": "string"
}
}
}
},
"Lists": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"Id": {
"type": "string"
},
"Name": {
"type": "string"
}
}
}
},
"ItemCreate": {
"type": "object",
"additionalProperties": false,
"x-ntx-dynamic-schema": {
"operationId": "GetFieldsCreate",
"parameters": {
"siteUrl": {
"parameter": "siteUrl"
},
"listName": {
"parameter": "listName"
}
},
"value-path": "Schema/Items"
}
}
},
"securityDefinitions": {
"functions_auth": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://api.example.com/oauth2/authorize",
"tokenUrl": "https://api.example.com/oauth2/token",
"scopes": {
"Sites.ReadWrite.All": "modify sites",
"Sites.Read.All": "read sites"
"offline access" : "Access to resource on behalf of the user for an extended time"
}
}
}
}