Environment Map Extension User Defined Function object

Use the Environment Map Extension User Defined Function object to create, modify, delete, and restore user-defined map functions within environment data maps.

Overview

You must have the Environment Management Full Access or the Environment Management privileges to use this API object. Extensible user-defined map functions allow you to link multiple standard function steps in a defined sequence to perform sophisticated transformations between profile fields in an extended Map. With the Environment Map Extension User Defined Function object, you can:

Retrieve the properties of an extended user-defined function
Create new, extensible user-defined functions
Update the configuration of an extended user user-defined function
Delete an extended user-defined function
Restore a deleted extended user-defined function

The actions available with this API object directly represent how you interact with extensible user-defined functions in the user interface. After using this API object, you can use the Environment Map Extension object to map through these extensible user-defined functions as part of a greater Map extension. The Environment Map Extension User Defined Function object is most useful for Integration Pack developers who need the flexibility to accommodate more complicated mapping logic for their specific business cases.

note

Creating user-defined functions using this object exists only at the environment extension level and are tied to a single map extension only; you cannot reference process-level functions in extensions. You can reuse a given function within a single map extension but cannot reuse it across multiple maps within an integration pack or across environments. User-defined functions are their own entities and are saved separately from extended maps that may reference them. After you save the Environment Map Extension object, the new versions of the user-defined functions communicate to the runtime.

This API supports all user-defined functions except:

SQL Lookups
Document Cache lookups
Get Properties
Set Properties
Set Trading Partners

Though you cannot create new Cross Reference Tables, you can look up existing Cross Reference Tables.

Structure

<EnvironmentMapExtensionUserDefinedFunction id="" environmentMapExtensionId="" name="" description="" deleted="" createdDate="" createdBy="" modifiedDate="" modifiedBy="">
   <Inputs>
       <Input name="" key=""/>
        .
        .
        .
      <Input name="" key=""/>
   <Inputs>
   <Outputs>
       <Output name="" key=""/>
        .
        .
        .
      <Output name="" key=""/>
   </Outputs>
   <Steps>
       <Step position="" cacheType="" id="" type="">
           <Inputs>
               <Input default="" name="" key=""/>
           </Inputs>
           <Outputs>
               <Output name="" key=""/>
           </Outputs>
           <Configuration>
               .
               .
               .
           </Configuration>
       </Step>
   </Steps>
   <Mappings>
       <Mapping fromFunction="" fromKey="" toFunction="" toKey=""/>
       <Mapping fromFunction="" fromKey="" toFunction="" toKey=""/>
   </Mappings>
</EnvironmentMapExtensionUserDefinedFunction>

Field	Type	Description
Filter	Filter	Filter
environmentMapExtensionID	string	The ID of an environment map extension. Important: This and other Environment Map Extension API objects require the client to know the ID of the environment map extension. In the user-defined function interface, click Copy EME ID to easily copy this ID for use in your API requests, or query the Environment Map Extensions Summary object.
id	string	Required. Represents the unique, system-generated ID of the extended user-defined function.
name	string	Required. Represents the name of the user-defined function component.
description	string	Optional. Additional details about the user-defined function component.
deleted	string	This variable indicates the deleted status of the user defined function component. If the value is true, it indicates the deletion of the referenced user-defined function. A false value indicates that the referenced user-defined function is not deleted and is available for use.
createdDate	numeric	Timestamp of the creation of the user-defined function.
createdBy	string	The user ID of the user who created the user-defined function.
modifiedDate	string	Timestamp of when the user-defined function was last updated.
modifiedBy	string	The user ID of the user who last updated the user-defined function.
Inputs/Outputs	string	Required. Lists the function's input and outputs according to their user-given names and keys. You must list inputs and outputs sequentially in order according to their key values. See the following row for more information. When creating or updating functions, it requires all input and output values in the request regardless if they are to be mapped or populated with a default value. The maximum number of inputs or outputs is 100.
key	numeric	Required. The number that represents the order in which the function's inputs or outputs appear. For a given function, the first input or output has a key attribute value of 1, the second a key attribute value of 2, and so on. Note: The `key` must start at 1 and then increment by one number for the list of inputs and outputs, respectively. The sequence of inputs or outputs is critical and varies for each function type.
Steps	string	Required. Defines the individual function steps and the order in which they need to occur within the greater user-defined function. The following attributes are used: 1.`position` - represents the step's number order in the greater function. 2.`cacheType` - indicates the caching behavior of the individual function step. The allowed `cacheType` values are:1.`None` (default, if omitted in the request)— It does not use Map function caching. 2. `ByDocument` — Caches the map function’s input and output values for each processed document. 3. `ByMap` — Caches the map function’s input and output values for each processed map. - `id` - represents the function step's ID in the format of "FUNCEXT--xxxxxxxxxx". 4. `type` - represents the type of function (for example, "MathCeil" or "CustomScripting"). Within the `Steps` element, you also need to define the following `input` and `output` variables for each function step: 1. `default` - Optional. Specifies the input value that the function uses if not provided by the user. 2. `name` - the user-defined name of the associated input or output. Note: The user interface automatically uses the used function type as the step name, but you can use this API object to change function step names. 3. `key` - the number ID assigned to a function step. This key is used to map function steps together in the `Mappings` attribute.
Configuration	complex	Required. Represents the additional configuration requirements needed to create or modify individual standard functions within the greater user-defined function. This element is only applicable to certain function step types. See the section Map Function reference for information and for details about how to properly construct or interpret these additional configuration requirements.
Mappings	complex	Required. Defines the mapping of inputs and outputs for the user-defined function and each function step. It uses the following attributes: 1. `fromFunction` - represents the function ID from which you are mapping. 2. `fromKey` - represents the function's output key from which you are mapping. 3. `toFunction` - represents the function ID to which you are mapping. 4. `toKey`- represents the function's input key to which you are mapping.

Supported operations

GET	QUERY	CREATE	UPDATE	EXECUTE	DELETE
Supported	Not Supported	Supported	Supported	Not Supported	Supported

Using the GET operation

The GET operation retrieves an extensible user-defined function associated with a given environment map extension function ID.

Using the CREATE operation

The CREATE operation creates a new extensible user-defined function. User-defined functions created using the Environment Map Extension User Defined Function object exists only at the environment extension level and are tied to a single map extension only.

When creating a new user-defined function, you define individual function steps that make up the greater user-defined function. Then, in the <Mappings> section of the request, you determine how to map or link each step to and from the function's input and output.

caution

Creating new functions requires all existing input and output values in the request regardless if they are mapped or populated with a default value. Otherwise, it overrides and removes those variables from the function.

Using the UPDATE operation

The UPDATE operation updates the extended configuration for a single user-defined function.

caution

Updating functions require all existing input and output values in the request regardless if they are mapped or populated with a default value. Otherwise, it overrides and removes those variables from the function.

Using the DELETE operation

The DELETE operation deletes the specified user-defined function. Deleted user-defined functions return a status of true and are no longer available for use in an API call or on the user interface.

Restoring a deleted user-defined function

Reinstate a deleted user-defined function by providing the function's id in a CREATE operation. You cannot make changes to a function during restoration (in other words, you cannot edit its values in a RESTORE request). By restoring a deleted function, it becomes available for use in an API call and in the user interface. After a successful RESTORE operation, the function returns a deleted status of false. Samples appear later in this topic.