APIs Category

The apps category contains items based on their purpose.

In this section, you can find information on the following topics:

• Administrative toolbar
• Specifying properties
• Create an API
• Delete an API
• Creating data get APIs
• Creating data put APIs

Administrative toolbar

Longview Designer includes an administrative toolbar. The buttons that appear on the administrative toolbar may vary depending on the tool or editor you have open in the workspace:

Specifying properties

Properties are general information about the API. The name of an API is only referenced in the REST URI and generally should be kept short.

Create an API

You can create an API by:

• Starting with a template, or
• Duplicating an existing API

To create a new API, event, or configuration library from a template:

1. Navigate to the Design module.
2. Expand the folder that relates to the purpose of the API you which to create.
3. Click New.
4. A new tab appears with the properties page open.

To create a new API by duplicating an existing one:

1. Navigate to the Design module.
2. Expand the folder that relates to the purpose of the API you which to create.
3. Expand the Existing folder under the specific type of API.
4. Right-click on the item you wish to copy and select Duplicate.
5. A new tab appears with the properties page open, containing all the settings and documents in the duplicated item.

Delete an API

If you have the appropriate authorization, you can use Longview Client to delete an API.

Creating data get APIs

You can use Longview Designer to create APIs that will export data from the Longview database. The target file may contain a single column of values or multiple columns of values. Depending on the type of export you would like to create, you can use either the Data GET – Single Value or Data GET – Multi value template.

Note: Variables can be used but they will need to be passed as a parameter along with their value in the REST URI or a 500 Internal Server Error will be returned.

Specifying properties

You can use Longview Designer to specify properties for a new data API.

For more information, see “Specifying properties”.

Specifying the Data Area Definition

Use the Data Area Definition to create a dataspec document (.lvdsp) used to define the area to be exported.

1. In the Options table, complete the following field

   Field	Description
   Data Type	Specify the data to be queried using one of the following options: ADJUSTED—Indicates that data queries include adjustments made via journal entries UNADJUSTED—Indicates that data queries exclude adjustments made via journal entries Default is ADJUSTED.
   Download Type	Specify the type of data to be downloaded using one of the following options (download option specific in brackets): All data—Indicates that all data within the data area definition is downloaded (STANDARDALL). Exclude parent values—Indicates that parent data is excluded in the download (STANDARDLEAFONLY) Exclude parent and calculated values—Indicates that only leaf data that was submitted to the database via import, input or event calculation is included in the download (LEAFDATA). Default is All data.

2. In the Data Area table, complete the following:
   • Schedule: This field displays only if your system is configured to use schedules and you have access to schedules.
     1. The default of None indicates the export spec is for base data only.
     2. Specify the schedule to use for the import spec, and the schedule dimensions appear at the bottom of the list of Dimensions.
   • Complete the following fields for each dimension:

     Note: The Spec and Level fields are not applicable if a symbol contains a variable.

     Field	Description
     Symbols	Type a symbol name. Alternatively, you can use the symbol selector. To add more than one symbol for a dimension, select a row containing the dimension for which you want to add another symbol and click Symbol. To move a symbol up or down within a dimension, click Move Up or Move Down.
     Spec	Indicate the symbol specification using one of the following values: All—Includes all symbols within the selected symbol’s hierarchy. Leaf—Includes only leaf symbols within the selected symbol’s hierarchy. Parent—Includes only parent symbols within the selected symbol’s hierarchy. Root and Parent—Includes only root and parent symbols within the selected symbol’s hierarchy.
     Level	Specify the number of levels down from the symbol to be included in the data area.

3. Use Additional Configuration to specify any other Data Area Definition features you wish to use. Additional Configuration is a code editor that allows you to enter data area definition functions to be included in the data area.
   For more information on the code editor, see “Using the code editor”.

   Typical use of Additional Configuration in a data area definition would be to:

   # Add an attribute filter using the AttributeFilter function

Specifying the Data Area Export Spec

Note: Exported files will be in CSV format with comma (,) delimiters and period (.) decimals. 

To create the data area export spec:

1. For a multiple value, file-based export: in the Values Dimension table complete the following field:

   Field	Description
   Dimension corresponding to values	Specify the dimension for which there are multiple value fields.

2. The Dimension Definitions section is used to specify how each dimension is processed during export. For Dimension Definitions, complete the following:
   • Schedule: This field displays only if your system is configured to use schedules and you have access to schedules.
     • The default of None indicates the export spec is for base data only.
     • Specify the schedule to use for the import spec, and the schedule dimensions appear at the bottom of the list of Dimensions.
   • For each dimension, complete the following fields:

     Field	Description
     Dimension	The name of the dimension.
     Type	Specify the type of relationship between dimension symbols and field values in the data source using one of the following values: Map—The dimension symbols are mapped to values as specified in the indicated map Match—The dimension symbols are written out with their names.
     Field Position	This field is available only when Type is Map or Match. Specify the field position to assign the dimension to using a positive integer. For example, for the Accounts dimension, type 3 if the account will be the third column of the data target.
     Symbol	This field is available only when Type is Unique. Type the symbol name for the specified dimension to which the data is imported. Alternatively, you can use the symbol selector. Note: You can also use a variable to define the symbol.
     Map Location	This field is available only when Type is Map. Indicate the location of the map using one of the following values: Internal—Indicates the map exists inside the database, created using the Mappings editor. For more information, see “Maintaining mappings”. External—Indicates the map exists as a file, such as a text file on your local machine or network location. Document—Indicates the map exists as a document within the Symbol Maps folder of the app.
     Map	This field is available only when Type is Map. Do one of the following: If you selected Internal as the Map Location, select a map from the list of available maps in the system. If you selected External as the Map Location, type the path of the external map or click the ellipsis button ( ... ) to select the external map. If you selected Document as the Map Location, select a map from the list of available maps in the app. Note: You can use a variable for the Map field if the map location is Internal or External.

3. For a single value, file-based export: in the Value Field table complete the following field:

   Field	Description
   Value Field Number	Specify the field position at which the data value will be written using a number.

4. If the data target contains multiple value fields, the Value Fields section is available. Complete the following fields:

   Field	Description
   Field Position	Specify the field position of the value field using a positive integer, where the field position is the corresponding column in the data source containing the data. For example, if the value is exported to the third column in the target file, type 3.
   Symbol	Type the name of a symbol from the dimension indicated in Multiple Value Fields for Dimension for the value in the corresponding field position. Alternatively, you can use the symbol selector. Note: You can use a variable for the Symbol field.

5. In the Data Options table, complete the following fields:

   Field	Description
   Reverse value for credit accounts	Select this option to reverse the sign for numeric values for accounts with Credit as the Balance Type. For more information on the balance type in the ACCOUNTS dimension, see “Working with dimensions” in the Longview Application Administrator Guide. The default is No.
   Allow duplicate mappings	This option applies only when at least one dimension Type is Map. Select this option to indicate that duplicate mappings are permitted. If multiple mappings are found, the system does the following for each type of mapping: Exact—All duplicate Exact mappings are used so that the same value is imported to multiple data cells. If there are duplicate Exact and Wildcard or Range mappings, the Exact mapping is used, and the Wildcard or Range mapping is ignored. Wildcard—If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed. Range—If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed. If you do not select this option, duplicate mappings are not permitted. If multiple mappings are found, the system reports an error for each mapping. The default is No.
   Handling for duplicate records	Specify the way duplicate records are handled for the data import app using one of the following values: Output all—Specifies that each duplicate record will be written to the target file. Error—Specifies that duplicate records should not be allowed. The first entry is submitted. If a duplicate record is encountered, the system reports an error. Sum values—Specifies that duplicate records should be allowed and the value of all such records summed. If a duplicate record is encountered that contains text (versus numeric) data, it is treated as an invalid/error record. The default is Error.
   Maximum number of errors	Specify the maximum number of error records to permit before stopping the import process. The default is 0.
   Header option	Specify whether to create a header in the target file, using one the following values: None—Specifies that no header will be created and the first record in the file is a data record. Auto—Specifies that a single header record is created in the target file. The header will contain the description of the dimension for each field that is a dimension, and “Value” for the value field The description of each symbol in a multiple value export. Custom—Specifies that the header records will be manually entered in the Custom header field.
   Custom header	When the header option is set to Custom, enter the header records in the form: “header record”, “...”, “header record”. Each header record is output on a new line in the target file.

6. You can optionally specify filters to apply when exporting data. For each filter type an expression using the following guidelines:
   • The expression can be joined together by two or more expressions using AND or OR and grouped by brackets, as appropriate.
   • Each expression uses field names, operators, and values as follows: FieldName EQ|NE|LE|LT|GE|GT Value. If Value is a string, enclose the string in double quotation marks. • You can optionally include wildcard characters (? and *) and symbols for Value.

     Note: In this case do not enclose Value in double quotation marks.

   • You can optionally use symbols for operators, such as ==, !=, <=, <, >=, and >.
   • You must use Field# for FieldName to refer to a specific field on which you want to filter. For example, if Products is the fourth column in your target file and you want to filter Products to import only the Products_Default symbol, use Field4 == "Products_Default" as the expression.

     Note: For more information on creating expressions, see “Using conditional operators” and “Search” in the Longview Developer’s Guide.

Specifying Symbol Maps

Symbol Maps(.lvmap) specify instructions when the symbol names in your data source do not match the symbol names in your Longview database.

For more information, see “Developing Longview ImportSpecs, ExportSpecs, and external Maps” in the Longview Developer’s Guide.

For more information on using the code editor, see "Using the code editor".

Creating data put APIs

You can use Longview Designer to create APIs that will submit data to the Longview database. Depending on the format of your source data file, you can use either the Data PUT – Single Value or Data PUT – Multi value template.

Note: Variables can be used but they will need to be passed as a parameter along with their value in the REST URI or a 500 Internal Server Error will be returned.

Specifying properties

You can use Longview Designer to specify properties for a new data API.

For more information, see “Specifying properties”.

Specifying the Data Area Definition

Use Data Area Definition to create a dataspec document (.lvdsp) used to define the area to be imported to.

1. In the Data Area table, complete the following:
   1. Schedule: This field displays only if your system is configured to use schedules and you have access to schedules.
      1. The default of None indicates the export spec is for base data only.
      2. Specify the schedule to use for the import spec, and the schedule dimensions appear at the bottom of the list of Dimensions.
   2. Complete the following fields for each dimension:
   3. The Spec and Level fields are not applicable if a symbol contains a variable.

      Field	Description
      Symbols	Type a symbol name. Alternatively, you can use the symbol selector. To add more than one symbol for a dimension, select a row containing the dimension for which you want to add another symbol and click Symbol. To move a symbol up or down within a dimension, click Move Up or Move Down.
      Spec	Indicate the symbol specification using one of the following values: All—Includes all symbols within the selected symbol’s hierarchy. Leaf—Includes only leaf symbols within the selected symbol’s hierarchy. Parent—Includes only parent symbols within the selected symbol’s hierarchy. Root and Parent—Includes only root and parent symbols within the selected symbol’s hierarchy.
      Level	Specify the number of levels down from the symbol to be included in the data area.

2. Use Additional Configuration to specify any other Data Area Definition features you wish to use. Additional Configuration is a code editor that allows you to enter data area definition functions to be included in the data area. For more information on the code editor, see “Using the code editor”.

Typical use of Additional Configuration in a data area definition would be to

# Add an attribute filter using the AttributeFilter function.

Specifying the Data Area Import Spec

Data area import specs (.lvimp) are used to import data to a data area. The source data may contain a single column of values or multiple columns of values.

Note: Incoming files are required to be in CSV format with comma (,) delimiters and period (.) decimals.  The import file is sourced from the body of the REST request header.

To create a data area import spec:

1. Right click on the Data Area Import Spec document.
2. Fill in the data source.

   Data source	Description
   Number of header records to filter	Specify the number of header rows to filter on import. If you leave the value as the default value of 0, the system assumes your data source starts with data records with no header rows.
   Number of footer records to filter	Specify the number of footer rows to filter on import. If you leave the value as the default value of 0, the system assumes your data source ends with data records with no footer rows.

3. For a multiple value, file-based import: in the Values Dimension table, complete the following fields:

   Field	Description
   Dimension corresponding to values	Specify the dimension for which there are multiple value fields.

4. The Dimension Definitions section is used to specify how each dimension is processed during import. For Dimension Definitions, complete the following:
   • Schedule: This field displays only if your system is configured to use schedules and you have access to schedules.
     • The default of None indicates the import spec is for base data only.
     • Specify the schedule to use for the import spec, and the schedule dimensions appear at the bottom of the list of Dimensions.
   • For each dimension, complete the following fields:

     Field	Description
     Dimension	The name of the dimension.
     Type	Specify the type of relationship between dimension symbols and field values in the data source using one of the following values: Consecutive—The values encountered in the data source are placed consecutively in the dimension starting at the indicated symbol, moving in priority order through the indicated symbol’s siblings. Note: Consecutive is designed to work with a symbol existing in only one hierarchy. If the symbol belongs to more than one hierarchy, the behavior used to determine the siblings is undefined and may be affected by hierarchy reorganizations and imports/exports. You can specify only one dimension as Consecutive. Map—The values encountered in the data source are mapped to dimension symbols as specified in the indicated map. Match—The values encountered in the data source are matched to the dimension symbols exactly. Unique—All values encountered in the data source are placed in the specified dimension symbol. If you select this option, you can use the variables you defined on the Variables page for the specified symbol.
     Field Position	This field is available only when Type is Map or Match. Specify the field position corresponding to the dimension using a positive integer. For example, for the Accounts dimension, type 3 if the account is in the third column of the data source.
     Symbol	This field is available only when Type is Consecutive or Unique. Type the symbol name for the specified dimension to which the data is imported. Alternatively, you can use the symbol selector. Note: You can also use a variable to define the symbol.
     Map Location	This field is available only when Type is Map. Indicate the location of the map using one of the following values: Internal—Indicates the map exists inside the database, created using the Mappings editor. For more information, see "Maintaining mappings". External—Indicates the map exists as a file, such as a text file on your local machine or network location. Document—Indicates the map exists as a document within the Symbol Maps folder of the app.
     Map	This field is available only when Type is Map. Do one of the following: If you selected Internal as the Map Location, select a map from the list of available maps in the system. If you selected External as the Map Location, type the path of the external map or click the ellipsis button ( ... ) to select the external map. If you selected Document as the Map Location, select a map from the list of available maps in the app. Note: You can also use a variable for the Map field if the map location is Internal or External.

5. For a single value, file-based import: in the Value Field table complete the following field:

   Field	Description
   Value Field Number	Specify the field position at which the data value will be written using a number.

6. If the data source contains multiple value fields, the Value Fields section is available. Complete the following fields:

   Field	Description
   Field Position	Specify the field position of the value field using a positive integer, where the field position is the corresponding column in the data source containing the data. For example, if the value is in the third column in the import file, type 3.
   Symbol	Type the name of a symbol from the dimension indicated in Multiple Value Fields for Dimension for the value in the corresponding field position. Alternatively, you can use the symbol selector. Note: You can use a variable for the Symbol field.

   Note: You can delete a value field by selecting a value field row and clicking Delete.

7. In the Data Options table, complete the following fields:

   Field	Description
   Data Import Method	This field identifies if the source file will always have a complete replacement of the data in the target dataarea or if it will support partial changes. Full – All data for the target space will be included in the source file, any records not included in the file will be assumed to be zero values. Incremental – Only those records included in the import file will be uploaded to the target space
   Reverse value for credit accounts	Select this option to reverse the sign for numeric values for accounts with Credit as the Balance Type. For more information on the balance type in the ACCOUNTS dimension, see “Working with dimensions” in the Longview Application Administrator Guide. The default is cleared.
   Allow duplicate mappings	This option applies only when at least one dimension Type is Map. Select this option to indicate that duplicate mappings are permitted. If multiple mappings are found, the system does the following for each type of mapping: Exact—All duplicate Exact mappings are used so that the same value is imported to multiple data cells. If there are duplicate Exact and Wildcard or Range mappings, the Exact mapping is used, and the Wildcard or Range mapping is ignored. Wildcard—If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed. Range—If no Exact mappings are found, the value is imported to the first Wildcard or Range mapping listed. If you do not select this option, duplicate mappings are not permitted. If multiple mappings are found, the system reports an error for each mapping. The default is No.
   Handling for duplicate records	Specify the way duplicate records are handled for the data import app using one of the following values: Use first record—Specifies that the first entry of duplicate records should be used. If a duplicate record is encountered, the system does not report an error. Use last record—Specifies that the last entry of duplicate records should be used. If a duplicate record is encountered, the system does not report an error. Error—Specifies that duplicate records should not be allowed. The first entry is submitted. If a duplicate record is encountered, the system reports an error. Sum values—Specifies that duplicate records should be allowed and the value of all such records summed. If a duplicate record is encountered that contains text (versus numeric) data, it is treated as an invalid/error record. Use first record—Specifies that the first entry of duplicate records should be used. If a duplicate record is encountered, the system does not report an error. The default is Error
   Maximum number of errors	Specify the maximum number of error records to permit before stopping the import process. The default is 0.
   Submit if fewer than maximum number of errors	Select this if the Number of errors before processing stops is greater than 0 and you want to allow for the import to submit the valid records and report the error records.  If set to FALSE then no submission will occur if there are any errors. The default is FALSE.

8. For each filter type an expression use the following guidelines:
   • The expression can be joined together by two or more expressions using AND or OR and grouped by brackets, as appropriate.
   • Each expression uses field names, operators, and values as follows: FieldName EQ|NE|LE|LT|GE|GT Value. If Value is a string, enclose the string in double quotation marks.
   • You can optionally include wildcard characters (? and *) and symbols for Value.

     Note: In this case do not enclose Value in double quotation marks.

   • You can optionally use symbols for operators, such as ==, !=, <=, <, >=, and >.
   • You must use Field# for FieldName to refer to a specific field on which you want to filter. For example, if Products is the fourth column in your import file and you want to filter Products to import only the Products_Default symbol, use Field4 == "Products_Default" as the expression.

Note: For more information on creating expressions, see “Using conditional operators” and “Search” in the Longview Developer’s Guide.

Specifying Symbol Maps

Symbol Maps(.lvmap) specify instructions when the symbol names in your data source do not match the symbol names in your Longview database.

For more information, see “Developing Longview ImportSpecs, ExportSpecs, and external Maps” in the Longview Developer’s Guide.

For more information on using the code editor, see "Using the code editor".