Dataset comment extraction data processing API

Function¶

Extracts the comments and attachments present in datasets of the Analytical Workspace. To do this, the data from which to extract the comments (process, workspace, dimensions, etc.) must be specified in the body of the request.

Once the request has been made, the system will create a compressed (.zip) folder containing an XLSX file with the extracted data and any attachments.

User requirements¶

To use these APIs, the user must be attributed a role for which the following functions are enabled:

0001836 - System Reports: Comments
0004152 - AIH System Reports: Comments and Attachments

Details of XLSX file contents¶

The XLSX file will contain the following elements.

Element	Notes
Forms	-
Custom fields	- If a field is encoded, the description will be unencoded. - The Analytical Workspace data values for fields on which the Personal Data Protection option is active will be exported in encrypted form.
Dimensions	- All dimensions assigned to this form are filtered on the basis of the caller's user rights. - If a dimension is filtered by a node of the same dimension, all the comments on its children will be shown. If there are further sub-nodes, all the comments on all levels will be shown. - The names of the dimensions are based on the language of the calling user's application. - The descriptions of the dimension elements are in the descriptions language of the calling user's profile, or in the fallback language if that description does not exist. - Descriptions of elements of the analytical dimensions on which the Personal Data Protection option is active are exported encrypted.
Value	- Numeric value of the field (if present). To the second decimal digit - Only for MULTIDIMENSIONAL forms
Comment type	Specifies the origin of the comment, or how the comment was inserted ("Navigation" or "Data Entry")
Comments	If there are multiple comments on the same form, all the necessary rows are duplicated, differing only by the Comment field.
Attachment	- The Attachment field reports the file name as a hyperlink, which opens the relative file. - Attachments are included in the compressed folder returned by the API. - If there are multiple comments on the same form, these are inserted in subsequent rows, duplicating everything but leaving the fields empty up to the Comment field. - If there are several attachments with the same file name, they are differentiated by default by the operating system.
User	The last user to have edited the comment or attachment.
Date	The date of the last change.

URL¶

/aih/comments/v1/database_id

Parameters¶

The following parameters can be entered in the body of the request:

Parameter	Description	Type	Required	Example in JSON format
process	Process from which to extract comments.	String	Optional	"process":
aw	Analytical workspace from which to extract comments.	String	Mandatory	"aw":
datasets	Dataset from which to extract comments.	String	Mandatory	"dataset":
fields	Dimensions from which to extract comments Filters based on the values of a specific dimension. The Name field must contain the field ID, while the Values array must contain the descriptions (in the correct language) to be searched. You can filter using the following fields: - Scenario - Period - Entity - Account - Variation/Detail types - Category - Custom dimensions from 1 to 5 - Currency - CTP entity - CTP Custom Dimension 2 - Cod_Prospetto - Custom Fields (text, number and date) If the dataset is partitioned by Business Cycle or Business Cycle and Entities and does not contain a Scenario, Period and/or Entity field, the form can be filtered in any case, based on the Scenarios, Periods and/or Entities by which they have been partitioned.	String	Mandatory	Copy `"fields":[ { "name":<string>, "values":[<string>,<string>...] }, ...`
includeNullValues	Includes empty dimension fields in the document. Default: false.	Boolean	Optional	"includeNullValues":
columnsAvailable	Columns visible in the document. If not present, all columns will be visible.	String	Optional	"columnsAvailable":
Form type	formType: "LINE_BY_LINE" or "MULTIDIMENSIONAL" Specifies the type of form to be extracted. Line-by-Line is the default, but is good practice to insert it.

Examples¶

API for filtering based on the Scenarios, Periods and/or Entities by which they are partitioned¶

Copy

"fields":[
{
"name":"COD_SCENARIO"/"COD_PERIODO"/"COD_ENTITY",
"values":[<string>,<string>...]
},
{
"name":"COD_SCENARIO"/"COD_PERIODO"/"COD_ENTITY",
"values":[<string>,<string>...]
}
]

API for extracting comments from dataset "0000002" in Analytical Workspace "00000001"¶

Parameters: Analytical Workspace and Dataset
Body:

Copy

{
    "aw":"00000001",
    "dataset":"0000002"
}

API for extracting comments from dataset "0000002" in Analytical Workspace "00000001" belonging to the "ACT" process¶

Parameters: Analytical Workspace, Dataset and Process
Body:

Copy

{
    "aw":"00000001",
    "dataset":"0000002",
    "process":"ACT"
}

API for extracting comments from dataset "0000002" in AW "00000001", belonging to process "ACT", with Scenario "2020_ACT", including empty elements.¶

Parameters: Analytical Workspace, Dataset, Process and Scenario
Body:

Copy

{
    "aw":"00000001",
    "dataset":"0000002",
    "process":"ACT",
    "fields":[
        {
            "name":"scenario",
            "values":["2020_ACT"],
            "includeNullsValues":true
        }
]
}

API for extracting comments from dataset "0000002" in AW "00000001", belonging to process "ACT", with Scenarios "2020_ACT" or "2018_ACT"¶

Parameters: Analytical Workspace, Dataset, Process and Scenario
Body:

Copy

{
    "aw":"00000001",
    "dataset":"0000002",
    "process":"ACT",
    "fields":[
        {
            "name":"scenario",
            "values":["2020_ACT","2018_ACT"]
        }
            ]
}

API for extracting comments from dataset "0000002" in AW "00000001", belonging to process "ACT", with Scenarios "2020_ACT" or "2018_ACT" and period "01", including the Period's empty fields¶

Parameters: Analytical Workspace, Dataset, Process and Scenario
Body:

Copy

{
    "aw":"00000001",
    "dataset":"0000002",
    "process":"ACT",
    "fields":[
        {
            "name":"scenario",
            "values":["2020_ACT","2018_ACT"]
        },
        {
            "name":"scenario",
            "values":["01"],
            "includeNullValues":true
        }
            ]
}