Views:

This article is for an API Partner to retrieve necessary information on the conditional logic rules (clauses) within a questionnaire.

Contents

Summary

Returns information on the conditional logic rules (clauses) within a questionnaire and the conditions that make up the clause. Clauses can show logic on a given question, option or row.

Pre-requisites: Valid subscription key and organization UUID for the respective Disclosure API environment.

Note - Logic: Conditional logic is typically only used to control the questionnaire based an answer made in previous questions, question visibility is also handled by “Tag Matching” based on the organizations tags. See “API Overview” section.

Note - Terminology: Saying a condition is “checking the value of” a question/option/row means that is the answer value that is being referenced to compare to the condition rules.

GET Request

URLs

Sandbox: https://api-pre.cdpgreenstar.net/asp/response/questionnaire/clauses

Production: https://api.cdp.net/response/questionnaire/clauses

Headers/Variables

subscription-key (header): For authorized user, the primary/secondary subscription key.

organization-id (optional header): Enter the UUID for the organization’s response.

Body

NULL

Response

Top Level: Clause

Information regarding the clause and details of the questions it applied to.

Note: The response from this endpoint is not controlled by Tag Matching. All clauses and conditions, for an entire questionnaire, are returned each time regardless of if relevant to the provided disclosing organization.

Field table
 

Field

Description

Data Type

id

The UUID for the clause/rule.

string

message

Not in use.

string

questionId

The ID of the question the clause/rule applies to.

string

rowId

The ID of the row the clause/rule applies too.

string

optionId

The ID of the option the clause/rule applies too.

string
question

Additional question information if the question is within a matrix question.

array

row

Additional row information if the clause/rule applies to a specific row.

array

conditions

Array list of the rules applied to the question/row/option.

array
leadingQuestionId

The parent question ID of the question the clause/rule applies too.

string

Schema
 
{
"id": "string",
"message": null,
"questionId": "string",
"rowId": "string",
"optionId": "string",
"question": [{...}],
"row": [{...}],
"conditions": [{...}],
"leadingQueestionId":"string"
}

Second Level: Question (n+1)

Additional question information if the question is within a matrix question.

Field table
 

Field

Description

Data Type

parentquestionId

The ID of the parent question of the question the clause/rule applies too if question is within a matrix.

string


Schema
 
[{

...
     "question": {

              "parentquestionId": "string",

}
...

}]

Second Level: Row (n+1)

Additional row information if the clause/rule applies to a specific row.

Field table
 

Field

Description

Data Type

id

The row ID.

string

complexQuestionId

The ID of the question the row is part of.

string

Schema
 
[{

...
     "row": {

       "id": "string",
        "complexQuestionId": "string",

}
...

}]

Second Level: Condition (n+1)

The details of the conditional logic that is applied.

Field table
 

Field

Description

Data Type

id

The ID of the individual condition within the given clause.

string

rowId

The ID of the row the condition is checking the value of.

string

clauseId

The ID of the clause the condition belongs too.

string

questionId

The ID of the question the condition is checking the value of.

string

value

The value used to compare the user’s answer value to.

Note: This can often be an option ID and isn’t always a literal value.
 

string

operand

How the value is compared against the user’s answer value:
 

  • “eq” = equal to
  • “neq” = not equal to

  • ”lt” = less than

  • ”gt” = greater than

  • “lte” = less than or equal to

  • ”gte” = greater than or equal to
string

logicalOperator

The AND/OR applied when there are multiple conditions within a clause.

string

index

The position of the condition within the clause (starts at 0).

integer


Known Issue - Nested Conditions: There is a limitation in the clauses endpoint which means that any nested conditions are not shown. As such, with the more complex rules it is not possible to accurately replicate these rules using the API response data.


Schema
 
[{

...
     "conditions": [{

      "id": "string",
      "rowId": "string",
      "clauseId": "string",
      "questionId": "string", 
      "value": "string",
      "operand": “string",
      "logicalOperator": "string",
      "index": integer

        }]
...

}]


JSON Response Example

Below is an example API response while calling the GET method for this endpoint. The data retrieved are the list of associated organizations. If organization ID is entered, the tagging information of that organization will also be displayed.
 

{
"id": "036c1b6c-8c22-49a1-99b1-e4dd60749540",
"message": null,
"questionId": "574e8ffa-4202-423e-a501-db1df4b6e188",
"rowId":  "addfa0b0-4ef5-4599-86dd-9f2976c31f95",
"optionId": null,
"question": {
                      "parentQuestionId": "1491b888-7468-4c3a-a4bb-d09bd3a714b7"
},
"row": {
              "id": "addfa0b0-4ef5-4599-86dd-9f2976c31f95",
              "complexQuestionId":  "1491b888-7468-4c3a-a4bb-d09bd3a714b7"
},
"conditions": [{
                                   "id": "c9bc6b9a-dd91-4c5c-a51c-c5a6ec316de7",
                                      "rowId": null,
                                      "clauseId": "036c1b6c-8c22-49a1-99b1-e4dd60749540",
                                      "questionId": "string",
                                      "value": "[\"bd1d8283-1b6d-4b6a-99eb-f944fcb81c24\"]",
                                  "operand": “eq”,
                                  "logicalOperator": “null,
                                  "index": 0
            }],
            "leadingQueestionId": "1491b888-7468-4c3a-a4bb-d09bd3a714b7"
} ]


Error Handling

1. Invalid Subscription Key

When an incorrect or invalid subscription key is entered, the following error is displayed:
 

{
"message": "Invalid subscription key",
"name": "Unauthorized",
"link": 401
}


2. Invalid Organization ID

When an incorrect or invalid organization key is entered, the following error is displayed:
 

{
"message": "Invalid organization id",
"name": "Unauthorized",
"link": 401
}


POST/PUT/DELETE Requests 

POST, PUT and DELETE requests are not implemented for this endpoint, preventing changes being made to a questionnaire's conditional logic.



If you have not found the answer you were looking for, please contact your Account Manager who will be able to assist you further.

Keywords: Disclosure API, API, ASP, API Partner
Comments (0)
Add a comment