Scripting SDK clients

The fetch job models are located in: Stylelabs.M.Sdk.Models.Jobs.

The available models are:

When creating a fetch job, the following arguments are always required:

To create a fetch job, pass the fetch job model to the CreateFetchJobAsync method of the jobs client. This returns the ID of the newly created job.

The following example will fetch an image from a public URL and link it to an asset with ID 1000:

var webFetchJob = new WebFetchJobRequest("Fetches an example image from the web.", 1000)
{
  Urls = new[] { "https://picsum.photos/200" }
};

long jobId = await MClient.Jobs.CreateFetchJobAsync(webFetchJob);

Email template entities contain the templates for sending emails. The variables can be resolved at runtime.

IMailTemplateEntity is a subtype of IEntity. It provides C# properties and methods for the members on the M.Mailing.Template entity definition.

To get these email templates, the client provides extra getters that are not available on the entities client. It allows fetching email templates by name. However, every operation on an IEntity still applies to IMailTemplateEntity. Saving and deleting IMailTemplateEntity objects is still done through the entities client.

A simple hello world template could look like this:

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");
var entity = await client.EntityFactory.CreateAsync(Constants.MailTemplate.DefinitionName);
var template = client.TypedEntityFactory.FromEntity <IMailTemplateEntity>(<ENTITY>);
template.Name = "Hello world template";
template.Subject[enUs] = "Hello there!";
template.Description[enUs] = "Hello";
template.Body[enUs] = "Hello {{Username}}!";
template.SetPropertyValue("M.Mailing.TemplateLabel", enUs, "Hello world template");

var templateVariable = new TemplateVariable
{
  Name = "Username",
  VariableType = TemplateVariableType.String
};
template.SetTemplateVariables(new[] { templateVariable });

await client.Entities.SaveAsync(<TEMPLATE>);

Emails can be sent to users by username, user ID, or by a broadcast. There are three respective overloads to the SendEmailNotificationAsync with the following input:

An email broadcast could be sent using the template:

var request = new MailRequestBroadcast
{
  MailTemplateName = "Hello world template"
};
request.Variables.Add("Username", "world");

await client.Notifications.SendEmailNotificationAsync(<REQUEST>);

This would send an e-mail containing "Hello world!", to everyone.

Real-time notifications can be sent to users by username, user ID, or by a broadcast. There are three respective overloads to the SendRealTimeNotificationAsync with the following input:

Here's an example of a real-time notification sent to the DemoUser:

var request = new RealtimeRequestByUsername()
{
  Title = "Your notification title",
  Link = new System.Uri("https://example.com")
};
request.Recipients.Add("DemoUser");
request.SetBody("Your description");
request.SetIcon("https://example.com/image.png");

await client.Notifications.SendRealTimeNotificationAsync(<REQUEST>);

The link is opened when the user clicks the notification.

This real-time request interface is built on the standard notifications API, which uses an options object that contains all the notification information. This object is directly passed from the IRealtimeRequest.Options property. Some helper methods have been provided to help configure this options object, for example, the body and the icon of the notification.

Sending confirmation emails to users can be done using IDs or usernames:

await client.Notifications.SendConfirmationEmailAsync("DemoUser");

This will send an email to the specified user, containing a secure link to activate their account.

To get a user's policy, use GetUserPolicyAsync:

var policy = await MClient.Policies.GetUserPolicyAsync(<USER_ID>);

To get a user group's policy, use GetUserGroupPolicyAsync:

var policy = await MClient.Policies.GetUserGroupPolicyAsync(<USERGROUP_ID>);

After making changes to a policy, you can update it as follows:

await MClient.Policies.UpdateAsync(<POLICY>);

You can use the Querying client to create queries and then run any of the following queries or iterate on results.

After running a query, an IQueryResult is returned. This result has the following properties:

When it is certain that a query only matches a single entity, use the SingleAsync method.

IEntity entity = await MClient.Querying.SingleAsync(<QUERY>);

When it is certain that a query only matches a single entity, use the SingleIdAsync method.

long? entityId = await MClient.Querying.SingleIdAsync(<QUERY>);

To query for one or more entities:

IEntityQueryResult queryResult = await MClient.Querying.QueryAsync(<QUERY>);

The IEntityQueryResult.Items contains the returned entities.

To query for one or more entity ids:

IIdQueryResult queryResult = await MClient.Querying.QueryIdsAsync(<QUERY>);

The IIdQueryResult.Items method contains the returned IDs (in long format).

When the query returns a small to medium size of results (the default configuration is 10,000 results maximum), it is easy to batch process the entities using an iterator.

In the following code snippet, an iterator is created:

IEntityIterator iterator = MClient.Querying.CreateEntityIterator(<QUERY>);

In the following code snippet, the iterator is used to batch process entities:

while (await iterator.MoveNextAsync())
{
  var entities = iterator.Current.Items;
  // Do something with the entities
}

The while loop automatically ends when the iterator has finished processing all the batches of entities.

When the query returns a small to medium size of results (the default configuration is 10,000 results maximum), it is easy to batch process the entity IDs using an iterator.

In the following snippet, an iterator is created:

IIdIterator iterator = MClient.Querying.CreateIdIterator(<QUERY>);

In the following code snippet, the iterator is used to batch process entity IDs:

while (await iterator.MoveNextAsync())
{
  var ids = iterator.Current.Items;
  // Do something with the ids
}

The while loop automatically ends when the iterator has finished processing all the batches of entities.

On the Query class it is possible to set the EntityLoadOptions property and the LoadConfiguration property. The first property was used by the old WebApiClient SDK and was deprecated in 3.0. In 3.1 the Query class and the load configurations were separated. We recommend that you do not use these properties, but pass the load configuration as an extra parameter when passing the query object, when applicable.

The following example snippet gets the ID of the PortalConfiguration category:

long? id = await MClient.Settings.GetCategoryIdAsync("PortalConfiguration");

The following example retrieves a setting called Authentication from the PortalConfiguration category:

IEntity setting = await MClient.Settings.GetSettingAsync("PortalConfiguration", "Authentication");

You can also get all the settings for a category. For example, the following snippet gets all the rendition settings:

IList IEntity renditionSettings = await MClient.Settings.GetSettingsForCategoryAsync("Renditions");

The GetUserAsync method gets a user by username.

The following example fetches the user entity named superuser:

IEntity superuser = await MClient.Users.GetUserAsync("superuser");

The GetUserGroupAsync method gets a user group by name.

The following example fetches the user group entity named superusers.

IEntity superusersGroup = await MClient.Users.GetUserGroupAsync("superusers");