unomi-sdk-node

Node module to interact with unomi.

:::info The uuid values used in these examples are not actual values. :::

Build

1. Open the folder

cd unomi-sdk-node/

2. Install dependencies

npm install

3. Build the module

npm run build

Connect to unomi

There are two ways to connect to unomi.

You can connect to unomi using the connect function with basic authentication:

import { connect } from "../node_modules/unomi-sdk-node";

const baseUrlUnomi = "https://unomi.example.com";
const baseUrlElasticsearch = "https://elasticsearch.example.com";
const username = "cdp_unomi";
const password = "F0RauuYEbz4GUwUG";

const unomisdk = connect({
    urlUnomi: baseUrlUnomi,
    urlElasticsearch: baseUrlElasticsearch,
    auth: {
        username: username,
        password: password
    }
});

You can also connect to unomi using the connect function with OAuth:

import { connect } from "../node_modules/unomi-sdk-node";

const baseUrlUnomi = "https://unomi.example.com";
const baseUrlElasticsearch = "https://elasticsearch.example.com";
const bearerToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";

const unomisdk = connect({
    urlUnomi: baseUrlUnomi,
    urlElasticsearch: baseUrlElasticsearch,
    auth: {
        bearerToken: bearerToken
    }
});

Functions

Profile

get

Get a profile.

Usage

const profileId = <string>;

unomisdk.profile.get(profileId);

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const profileId = "7461c378-c216-4697-9244-4be7257bc75c";

const profile = unomisdk.profile.get(profileId);

profile.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

allUsedProperties

Get all properties that are used in profiles.

Usage

unomisdk.profile.allUsedProperties();

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const properties = unomisdk.profile.allUsedProperties();

properties.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

count

Get the amount of profiles currently in Unomi.

Usage

unomisdk.profile.count();

Response

// success
{
    statusCode: 200,
    responseData: <int>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const count = unomisdk.profile.count();

count.then(data => {

    console.log(data);

}).catch(err => {

    console.log(err);

});

Rule

getAll

Get all rules.

Usage

unomisdk.rule.getAll();

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const rules = unomisdk.rule.getAll();

rules.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

get

Get a rule.

Usage

const ruleId = <string>;

unomisdk.rule.get(ruleId);

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const ruleId = "ccf46960-f50f-4c63-96ea-d27530262f10";

const rule = unomisdk.rule.get(ruleId);

rule.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

create

Create a rule.

Usage

const params = {
    metadata: {
        id: <string>,
        name: <string>,
        description: <string>
    },
    raiseEventOnlyOnceForSession: <boolean>,
    condition: {
        type: <string>,
        parameterValues: {
            operator : <string>,
            parameterValues: {
                eventTypeId: <string>
            }
        }
    },
    actions: [
        {
            type: <string>,
            parameterValues: {
                setPropertyName: <string>
                setPropertyValue: <string>
                setPropertyStrategy: <string>
            }
        }
    ]
};

unomisdk.rule.create(params);

Response

// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const params = {
    metadata: {
        id: "setContactInfo",
        name: "Copy the received contact info to the current profile",
        description: "Copies the contact info received in a custom event called 'contactInfoSubmitted' to the current profile"
    },
    raiseEventOnlyOnceForSession: false,
    condition: {
        type: "eventTypeCondition",
        parameterValues: {
            eventTypeId: "contactInfoSubmitted"
        }
    },
    actions: [
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(firstName)",
                setPropertyValue: "eventProperty::properties(firstName)",
                setPropertyStrategy: "alwaysSet"
            }
        },
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(lastName)",
                setPropertyValue: "eventProperty::properties(lastName)",
                setPropertyStrategy: "alwaysSet"
            }
        },
        {
            type: "setPropertyAction",
            parameterValues: {
                setPropertyName: "properties(email)",
                setPropertyValue: "eventProperty::properties(email)",
                setPropertyStrategy: "alwaysSet"
            }
        }
    ]
};

const rule = unomisdk.rule.create(params);

rule.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

Segment

getAll

Get all segments.

Usage

const sortOrder = <string>;
const limit = <int>;
const offset = <int>;

unomisdk.segment.getAll(sortOrder, limit, offset);

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const sortOrder = "asc";
const limit = 10;
const offset = 0;

const segments = unomisdk.segment.getAll(sortOrder, limit, offset);

segments.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

get

Get a segment.

Usage

const segmentId = <string>;

unomisdk.segment.get(segmentId);

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const segmentId = "63d58612-51ed-479a-adaf-7258ea4c17a8";

const segment = unomisdk.segment.get(segmentId);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

Note

The object in responseData will have the following structure:

const segment = {
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName:? <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>
        }
    ]
};

The conditionType of the subCondition will determine which properties the subCondition will have:

• profilePropertyCondition:
  • propertyName
  • comparisonOperator
  • propertyValue
• profileSegmentCondition:
  • matchType
  • segments

create

Create a segment.

note

This sdk also supports relative dates in unomi segment subConditions.

The prefix "dateExpr::" needs to be added to the propertyValue value when a date expression needs to be used. This prefix is necessary due to how validation works in this sdk. Otherwise the sdk would not know the difference between "now" in the context of text and "now" in the context of dates. This prefix is removed before sending the validated segment to unomi.

Here is an example for profiles whose "da__created" profile property is newer than 5 days ago:

subConditions: [
    {
        propertyName: "capture_properties.da__created",
        comparisonOperator: "greaterThan",
        propertyValue: "dateExpr::now-5d",
        conditionType: "profilePropertyCondition"
    }
]

The conditionType you use will determine which properties you have to use:

• profilePropertyCondition:
  • propertyName
  • comparisonOperator
  • propertyValue
• profileSegmentCondition:
  • matchType
  • segments

Nested subconditions don't work in this endpoint. Subconditions can only go one layer deep.

Usage

const params = {
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName?: <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | boolean | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>
        }
    ]
}

unomisdk.segment.create(params);

Response

// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const params = {
    name: "Marketeer",
    description: "Lorem ipsum dolor sit amet ...",
    scope: "459e18cb-348f-466f-811a-fdc4a296592f",
    tags: ["tech", "work", "manage"],
    systemTags: ["manual"],
    operator: "or",
    subConditions: [
        {
            propertyName: "classificationUuid",
            comparisonOperator: "equals",
            propertyValue: "3bb3e3b0-4285-11ea-aaef-0800200c9a66",
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "nbOfVisits",
            comparisonOperator: "between",
            propertyValue: [10, 30],
            conditionType: "profilePropertyCondition"
        },
        {
            matchType: "in",
            segments: ["1d600a47-12a7-4ac7-8797-645ebb07341d"],
            conditionType: "profileSegmentCondition"
        }
    ]
};

const segment = unomisdk.segment.create(params);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

update

Update a segment.

note

This sdk also supports relative dates in unomi segment subConditions.

The prefix "dateExpr::" needs to be added to the propertyValue value when a date expression needs to be used. This prefix is necessary due to how validation works in this sdk. Otherwise the sdk would not know the difference between "now" in the context of text and "now" in the context of dates. This prefix is removed before sending the validated segment to unomi.

Here is an example for profiles whose "da__created" profile property is newer than 5 days ago:

subConditions: [
    {
        propertyName: "capture_properties.da__created",
        comparisonOperator: "greaterThan",
        propertyValue: "dateExpr::now-5d",
        conditionType: "profilePropertyCondition"
    }
]

The conditionType you use will determine which properties you have to use:

• profilePropertyCondition:
  • propertyName
  • comparisonOperator
  • propertyValue
• profileSegmentCondition:
  • matchType
  • segments

Nested subconditions don't work in this endpoint. Subconditions can only go one layer deep.

Usage

const params = {
    id: <string>,
    name: <string>,
    description: <string>,
    scope: <string>,
    tags: <string[]>,
    systemTags: <string[]>,
    operator: <string>,
    subConditions: [
        {
            propertyName?: <string>,
            comparisonOperator?: <string>,
            propertyValue?: <string | int | boolean | string[] | int[] | null>,
            matchType?: <string>,
            segments?: Array<string>,
            conditionType: <string>

        }
    ]
}

unomisdk.segment.update(params);

Response

// success
{
    statusCode: 204,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const params = {
    id: "63d58612-51ed-479a-adaf-7258ea4c17a8",
    name: "Marketeer",
    description: "Lorem ipsum dolor sit amet ...",
    scope: "459e18cb-348f-466f-811a-fdc4a296592f",
    tags: ["tech", "work", "manage", "umami"],
    systemTags: ["manual"],
    operator: "or",
    subConditions: [
        {
            propertyName: "classificationUuid",
            comparisonOperator: "equals",
            propertyValue: "3bb3e3b0-4285-11ea-aaef-0800200c9a66",
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "nbOfVisits",
            comparisonOperator: "between",
            propertyValue: [10, 30],
            conditionType: "profilePropertyCondition"
        },
        {
            propertyName: "firstVisit",
            comparisonOperator: "greaterThanOrEqualTo",
            propertyValue: "2020-04-20",
            conditionType: "profilePropertyCondition"
        },
        {
            matchType: "in",
            segments: ["1d600a47-12a7-4ac7-8797-645ebb07341d"],
            conditionType: "profileSegmentCondition"
        }
    ]
};

const segment = unomisdk.segment.update(params);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

delete

Delete a segment.

Usage

const segmentId = <string>;

unomisdk.segment.delete(segmentId);

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const segmentId = "63d58612-51ed-479a-adaf-7258ea4c17a8";

const segment = unomisdk.segment.delete(segmentId);

segment.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

profileCount

Get the amount of profiles in a specified segment or array of segments.

Usage

const params = {
    segments: <string[]>,
    operator: <string>
}

unomisdk.segment.profileCount(params);

Response

// success
{
    statusCode: 200,
    responseData: <string>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const params = {
    segments: ["c91a600f-df5c-4c16-b8f8-f0c036f7b09a", "bbbdef55-bbac-4e76-a7b7-86a5fbd57161"],
    operator: "and"
}

const profileCount = unomisdk.segment.profileCount(params);

profileCount.then(data => {

    console.log(data);

}).catch(err => {

    console.log(err);

});

ComparisonOperator

getAll

Get all comparisonOperators.

Documentation

Link to documentation: https://hackmd.io/qbR7MYX6SxutO4Jespn1QA

:::info The object structure you see in the documentation is what actually gets sent to unomi. When you use this module, the object you send is what you see in the example of the segment create and update function. :::

Usage

unomisdk.comparisonOperator.getAll();

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const comparisonOperators = unomisdk.comparisonOperator.getAll();

comparisonOperators.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

MatchType

getAll

Get all matchTypes. (These are used for profileSegmentConditions.)

Documentation

Link to documentation: https://hackmd.io/qbR7MYX6SxutO4Jespn1QA

:::info The object structure you see in the documentation is what actually gets sent to unomi. When you use this module, the object you send is what you see in the example of the segment create and update function. :::

Usage

unomisdk.matchType.getAll();

Response

// success
{
    statusCode: 200,
    responseData: <object>
}

// no success
{
    statusCode: <int>,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <null>,
    response: <object>
}

// exception in module
{
    statusCode: 500,
    errorMessage: <string>,
    errors: <object[]>,
    exception: <string>,
    response: {
        method: <string>,
        url: <string>,
        body: <object | null>,
        successStatus: <int>
    }
}

Real World Example

const matchTypes = unomisdk.matchType.getAll();

matchTypes.then(data => {

    console.log(data);
    
}).catch(err => {

    console.log(err);
    
});

DateExpression

isValid

Validate a given date expression.
Returns a true or false.
true if the date expression is a valid date expression.
false if the date expression is not a valid date expression.

You can find some supported formats in comments in the code in the following file: "src/utils/validation.ts" at the "isValidDateExpression" function.

Note

More about date expressions can be found in the elasticsearch documentation: https://www.elastic.co/guide/en/elasticsearch/reference/7.x/common-options.html#date-math

Usage

const dateExpr = <string>

unomisdk.dateExpression.isValid(dateExpr);

Response

// valid date expression
true

// invalid date expression
false

Real World Example

const dateExpr = "now+1y/y"

const isValidDateExpr = unomisdk.dateExpression.isValid(dateExpr);