This documentation supports the 9.1 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

ARImport

Note

You can continue to use C APIs to customize your application, but C APIs are not enhanced to support new capabilities provided by Java APIs and REST APIs.

Description

Imports the indicated structure definitions to the specified server. Use this function to copy structure definitions from one BMC Remedy AR System server to another (see ARExport).

Privileges

BMC Remedy AR System administrator.

Synopsis

#include "ar.h"
#include "arerrno.h"
#include "arextern.h"
#include "arstruct.h"

int ARImport(
   ARControlStruct *control,
   ARStructItemList *structItems,
   char *importBuf,
   unsigned int importOption,
   char *objectModificationLogLabel,
   ARStatusList *status)

Input arguments

control

The control record for the operation. It contains information about the user requesting the operation, where that operation is to be performed, and which session is used to perform it. The user and server fields are required.

The runtime group specified in the control record does not affect import operations. Instead, that function uses the overlay group specified in the object property list in the imported object definition file. For information about runtime groups and the overlay group setting, see ARSetSessionConfiguration.

structItems

A list of zero or more structure items to import (identified by type and name). Specify NULL
for this parameter to import all structures in the import buffer.

1:

Form (includes all associated views) (AR_STRUCT_ITEM_SCHEMA)

5:

Filter (AR_STRUCT_ITEM_FILTER)

6:

Active link (AR_STRUCT_ITEM_ACTIVE_LINK)

8:

Character menu (AR_STRUCT_ITEM_CHAR_MENU)

9:

Escalation (AR_STRUCT_ITEM_ESCALATION)

10:

Distributed mapping (AR_STRUCT_ITEM_DIST_MAP)

12:

Container (AR_STRUCT_ITEM_CONTAINER)

14:

VUI (AR_STRUCT_ITEM_VUI)

16:

Application (AR_STRUCT_ITEM_APP)

20:

Association (AR_STRUCT_ITEM_ASSOCIATION)

30:

Form data (AR_STRUCT_ITEM_SCHEMA_DATA)

Note

You must specify AR_STRUCT_ITEM_SCHEMA to import a form. The three partial form types defined in ar.h (AR_STRUCT_ITEM_SCHEMA_DEFN, AR_STRUCT_ITEM_SCHEMA_VIEW, and AR_STRUCT_ITEM_SCHEMA_MAIL) do not contain complete form definitions and are used only for caching purposes.

Note

When you import an overlay that has inherited properties, those properties are inherited from the copy of the origin object that is on the server. If you import the origin object with the overlay, then the overlay will inherit properties from the imported object. If not, then the overlay will inherit properties from the object already on the server.

importBuf

A buffer that contains the definition text for the items specified for the structItems parameter. This buffer can contain other structure definitions, but the system imports only the specified items.

importOption

A value that indicates whether to replace objects being imported if they already exist and how to replace them. There are two sets of import options. Always set one of the basic options to indicate whether to replace objects. Set zero or more advanced options to further configure how ARImport handles inconsistencies between the objects on the server and the object definitions in the import buffer.

Basic options:

0:

Create a new objects and generate an error if an object already exists. (AR_IMPORT_OPT_CREATE)

1:

Overwrite an existing object. (AR_IMPORT_OPT_OVERWRITE)

Advanced options (add the values to enable more than one option):

16:

Check for conflicting data types and report an error. (AR_IMPORT_OPT_HANDLE_CONFLICT_ERROR).

32:

Check for conflicting data types and overwrite the existing object with the imported object. (AR_IMPORT_OPT_HANDLE_CONFLICT_OVERWRITE)

48:

Check for conflicting data types and do not change the existing object if there is a conflict. (AR_IMPORT_OPT_HANDLE_CONFLICT_NO_ACTION).

64:

Do not delete fields on the existing schema that are not in the imported schema. (AR_IMPORT_OPT_NOT_DELETE_FIELD).

128:

Check for duplicate entries and report an error. (AR_IMPORT_OPT_DATA_REJECT_FOR_DUP)

256:

Generate a new ID for a duplicate entry. (AR_IMPORT_OPT_DATA_NEWID_FOR_DUP)

512:

Overwrite existing entry with an imported duplicate. (AR_IMPORT_OPT_DATA_OVERWRITE_FOR_DUP)

1024:

Merge an existing entry with an imported duplicate. (AR_IMPORT_OPT_DATA_MERGE_FOR_DUP)

2048:

Generate a new ID for each entry. (AR_IMPORT_OPT_DATA_NEWID_FOR_ALL)

4096:

Do not delete VUIs of the existing schema that are not in the imported schema. (AR_IMPORT_OPT_NOT_DELETE_VUI).

8192:

Preserve the permissions of existing objects. (AR_IMPORT_OPT_NOT_OVERWRITE_PERMISSION)

16384:

Preserve all existing workflow attributes except the form list, the list of forms the workflow is attached to. (AR_IMPORT_OPT_WORKFLOW_PRESERVE_DEFN)

32768:

Add the forms in the imported workflow form list to the workflow form list of an existing schema instead of replacing the workflow form list of an existing schema with the imported one. (AR_IMPORT_OPT_WORKFLOW_MERGE_ATTACHLIST)

65536:

Preserve the change history of an existing object instead of replacing it with the change history of the imported object. (AR_IMPORT_OPT_PRESERVE_HISTORY)

2097152:

Overwrite all workflow attributes, but preserve the existing form list. (AR_IMPORT_OPT_WORKFLOW_PRESERVE_ATTACHLIST)

4194304:

Remove the forms included in the imported workflow form list from the workflow form list of the existing schema, but preserve the existing workflow attributes. (AR_IMPORT_OPT_WORKFLOW_REMOVE_ATTACHLIST)

8388608:

Overwrite full text option on existing field. (AR_IMPORT_OPT_OVERWRITE_FULL_TEXT_OPTION)

16777216:

Overwrite field display properties with properties from definition. (AR_IMPORT_OPT_OVERWRITE_DISP_PROPS)

objectModificationLogLabel

The version control label that the API function must apply to the object. If the label name does not exist on the server, the function creates it.

Ripple actions

Rename and Delete operations typically change multiple objects in addition to their primary target object. The Rename or Delete function must apply the version control label to all the objects that it affects.

Multiple API calls for a single user action 

Some user actions trigger a sequence of API calls. In that situation, the last API call in the sequence applies the version control label to the object. Thus, clients that create forms (like BMC Remedy Developer Studio does) should provide the label only to the last call. For example, when a form is created, a client might issue these calls:

  • ARCreateSchema
  • ARCreateMultipleFields
  • ARSetVUI
  • ARSetVUI
  • ARSetSchema

In this case, the objectModificationLogLabel value should be passed only to the last call, ARSetSchema, even though the user provides the label during the ARCreateSchema operation.

Operations on label-related forms

Version control labels cannot be applied to these forms:

  • AR System Version Control: Label
  • AR System Version Control: Labeled Object
  • AR System Version Control: Object Modification Log

Return values

status

A list of zero or more notes, warnings, or errors generated from a call to this function. For a description of all possible values, see Error checking.

See also

ARExport, ARExportToFile. See FreeAR for: FreeARStatusList, FreeARStructItemList.

Was this page helpful? Yes No Submitting... Thank you

Comments