Metadata pattern

You can extract and use metadata, such as the owner of a mix or a mix component, or the name of a user or a mix component.

You can retrieve metadata by using the Meta function in the expr.src property of either a service or an operation.

The function takes a single argument and returns the associated metadata. The available arguments are listed in section Meta arguments.

You can bind this metadata to variables both in service and operation properties, and use them in your mix. See Table 1 and Table 2 on how to use metadata in the markup of an operation or a service.

Table 1. Meta example with operation
Example Description
<request name="ServeState"
  service="Plato"
  fields="GET_ROLE">
  <prop name="expr.src"
    content-type="text/x-erlang"><![CDATA[
case Meta(user) of
  "gijoe@def.com" ->
    "Defend";
  "aristotle@edu.com" ->
    "Rule";
  "boxer@farm.com" ->
    "Work";
 _Otherwise ->
    "Error"
end.
  ]]></prop>
  <reply name="Defend"
    fields="defend"/>
  <reply name="Rule"
    fields="rule"/>
  <reply name="Work"
    fields="work"/>
  <reply name="Error"
    fields="error"/>
</request>
The ServeState operation is on an svc_expr service, called Plato.

This service can be anywhere in the configuration tree, and might have some additional markup.

The operation uses the Meta function with the user argument to tell who the user is, on whose behalf the operation is invoked.

Important: The user metadata is only available on operations.

The user might be anyone who has execute rights in the folder or mix folder that contains the ServeState operation.

Depending on who this user is, the request operation sends one of the four possible replies:

  • Defend, if the user is gijoe@def.com
  • Rule, if the user is aristotle@edu.com
  • Work, if the user is boxer@farm.com
  • Error, if the user is anyone else

The actual owner of the operation, that is, the one in whose configuration tree the operation is present, might be a fourth user. For example, admin@sparkl.com.

See Table 2 on an example with the owner metadata.

Table 2. Meta example with service
Example Description
<service name="Expr"
  provision="expr">
  <prop name="expr.src"
    content-type="text/x-erlang"><![CDATA[
Owner = Meta(owner).
  ]]></prop>
</service>
...
  <request name="Sign"
    service="Expr"
    fields="SIGN">
    <prop name="expr.bind.out"
      Owner="signature"/>
    <reply name="Ok"
      fields="signature"/>
  </request>
In this example, the Meta function is used to tell who the owner of the Expr service is. The owner is the user in whose configuration tree the service is present.

The result of the Meta function, that is, the owner of the service, is bound to the Owner static variable.

All operations on the Expr service can use this variable.

In this example, the Sign operation binds the Owner variable to its output field, signature.

Whenever the Sign operation is executed, it sends the Ok reply with the signature field, which contains the name of the user who owns the Expr service.

Meta arguments

The user argument is only available for operations. All other Meta arguments can be used in the markup of both operations and services.

The argument can be specified as:

  • atom
  • "string"
  • <<"utf8 binary">>

If the argument is a tuple, as in the case of {ancestor, "[SomeName]"}, {prop, "[name]"} and {prop, "[name]", "[attr]"}, this flexibility only applies to the first element of the tuple. The second and third elements, [SomeName], [name] and [attr], must be strings.

  • owner
    The name of the user in whose configuration tree the mix component resides.
    For example:
    Meta(owner) -> admin@sparkl.com
  • folder
    The folder containing the mix component.
    For example:
    Meta(folder) -> /Scratch/Reinsurance/
    Note: The name of the mix component is excluded from the path.
  • name
    The name of the mix component.
    For example:
    Meta(name) -> MyService
  • path
    The full pathname of the mix component. It is a combination of the arguments:
    For example:
    Meta(path) -> admin@sparkl.com/Scratch/Reinsurance/MyService
  • user
    The name of the user for whom the operation is invoked. It returns the value of undefined if the user is not signed in and thus known to SPARKL.
    Important: The user metadata is only available on operations.
    For example:
    Meta(user) -> user@foo.com
  • {ancestor, "[SomeName]"}
    Depending on the parent folders of the mix component, the function returns the atom true or false.
    It returns true if the mix component that contains the Meta function has any ancestor folder or mix folder with the name [SomeName].
    For example, the following always returns true:
    Meta({ancestor, "Home"}) -> true
  • {prop, "[name]"}
    The text content of the property whose name is [name]. It returns the value of undefined if the property does not exist.
    If the property does not exist on the mix component itself, the function goes up the configuration tree trying to find the closest parent folder which has such a property.
    For example:
    Meta({prop, "expr.src"}) -> ServiceProp = Meta({prop, "expr.src"}), "Ok".
  • {prop, "[name]", "[attr]"}
    The text value of the attribute [attr] on the property whose name is [name]. It returns the value of undefined if either the property or the attribute do not exist.
    If a property with this attribute does not exist on the mix component itself, the function goes up the configuration tree trying to find the closest parent folder which has such a property with the specified attribute.
    For example:
    Meta({prop, "expr.src", "type"}) ->  text/x-erlang