findOrCreateLabel( )

Developer Preview

Retrieves a label with a given name, or creates one if it doesn't exist.

Description

The findOrCreateLabel() function returns a Promise that resolves when the specified label is found or created.

Successful calls to findOrCreateLabel() always returns a label, which can be passed to subsequent function calls.

To find an existing label without potentially creating a new one, use getLabel() or queryLabels().

Admin Method

This function requires elevated permissions to run. This function is not universal and runs only on the backend.

Syntax

function findOrCreateLabel(displayName: string, options: FindOrCreateLabelOptions): Promise<FindOrCreateLabelResponse>

findOrCreateLabel Parameters

NAME

TYPE

DESCRIPTION

displayName

string

Display name to retrieve or create.

If an existing label is an exact match for the specified display name, the existing label is returned. If not, a new label is created and returned.

options

Optional

FindOrCreateLabelOptions

Language options.

Returns

Label that was found or created.

Return Type:

Promise<

FindOrCreateLabelResponse

NAME

TYPE

DESCRIPTION

label

ContactLabel

Label that was found or created.

newLabel

boolean

Indicates whether the label was just created or already existed.

If the label was just created, returns true. If it already existed, returns false.

Was this helpful?

Create a label (dashboard page code)

Copy Code

1import { labels } from 'wix-crm.v2';
2
3/*  Sample displayName value: 'At Risk' */
4
5export async function myCreateLabelFunction(displayName) {
6  
7  try {
8    const newLabel = await labels.findOrCreateLabel(displayName);    
9    console.log('Successfully created a new label:', newLabel);
10 
11    return newLabel;  
12  } catch (error) {
13    console.log(error);
14    // Handle the error
15  }
16}
17
18/* Promise resolves to: 
19 * {
20 *   "label": {
21 *     "namespace": "custom",
22 *     "namespaceDisplayName": "Labels",
23 *     "key": "custom.at-risk",
24 *     "displayName": "At Risk",
25 *     "labelType": "USER_DEFINED",
26 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
27 *     "_createdDate": "2023-12-25T08:38:36.138Z",
28 *     "_updatedDate": "2023-12-25T08:38:36.138Z"
29 *   },
30 *   "newLabel": true
31 * }
32 */

Create a label (export from backend code)

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { labels } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4
5/*  Sample displayName value: 'At Risk' */
6
7export const myCreateLabelFunction = webMethod(Permissions.Anyone, async (displayName) => {
8  
9  try {
10    const elevatedCreateLabel = elevate(labels.findOrCreateLabel);
11    const newLabel = await elevatedCreateLabel(displayName);    
12    console.log('Successfully created a new label:', newLabel);
13 
14    return newLabel;  
15  } catch (error) {
16    console.log(error);
17    // Handle the error
18  }
19});
20
21/* Promise resolves to: 
22 * {
23 *   "label": {
24 *     "namespace": "custom",
25 *     "namespaceDisplayName": "Labels",
26 *     "key": "custom.at-risk",
27 *     "displayName": "At Risk",
28 *     "labelType": "USER_DEFINED",
29 *     "legacyId": "65bd6a68-e10e-4831-8d92-c90e75be1570",
30 *     "_createdDate": "2023-12-25T08:38:36.138Z",
31 *     "_updatedDate": "2023-12-25T08:38:36.138Z"
32 *   },
33 *   "newLabel": true
34 * }
35 */
36

Find a label

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { labels } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4
5/* Sample displayName value: 'Active Customer' */
6
7export const myFindLabelFunction = webMethod(Permissions.Anyone, async (displayName) => {
8  
9  try {
10    const elevatedFindLabel = elevate(labels.findOrCreateLabel);
11    const label = await elevatedFindLabel(displayName);    
12    console.log('This label already exists:', label);
13 
14    return label;  
15  } catch (error) {
16    console.log(error);
17    // Handle the error
18  }
19});
20
21
22/* Promise resolves to: 
23 * {
24 *   "label": {
25 *     "namespace": "custom",
26 *     "namespaceDisplayName": "Labels",
27 *     "key": "custom.active-customer",
28 *     "displayName": "Active Customer",
29 *     "labelType": "USER_DEFINED",
30 *     "legacyId": "74f1e5c6-d9d5-4485-b272-13081ea35f38",
31 *     "_createdDate": "2023-12-25T06:13:21.000Z",
32 *     "_updatedDate": "2023-12-25T06:13:21.000Z"
33 *   },
34 *   "newLabel": false
35 * }
36 */

Create a new label and add it to a contact

This function creates a new label, gets the label's key, and then adds the label to the contact.

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { contacts, labels } from 'wix-crm.v2';
3import { elevate } from 'wix-auth';
4
5/* Sample contactId value: '2712ae1d-3f64-46c2-ac3a-94a6c2e29847'
6 * 
7 * Sample displayName value: 'Supplier'
8 */
9
10export const addNewLabelToContact = webMethod(Permissions.Anyone, async (displayName, contactId) => {
11  
12  try {
13    const elevatedCreateLabel = elevate(labels.findOrCreateLabel);
14    const elevatedLabelContact = elevate(contacts.labelContact);
15    const newLabel = await elevatedCreateLabel(displayName);
16    const labelKeys = [newLabel.label.key];
17    // Retrieve the new label's key
18    if (newLabel.newLabel) {
19      // Label contact
20      const contact = await elevatedLabelContact(contactId, labelKeys);
21      const contactLabels = contact.contact.info.labelKeys.items;
22
23      return contactLabels;
24    }
25    else {
26      return "Label was not added to contact.";
27    }
28  } catch (error) {
29    // Handle the error
30    console.log(error);
31  }
32});
33
34/* Promise resolves to: 
35 * [
36 *   "custom.contact",
37 *   "custom.supplier"
38 * ]
39 */