Create CI

Creates a resource of the class you pick, filling its fields from a YAML map. Reach for it when a rule has to register something in Clarive that was not there before: a user arriving from a directory lookup, or a revision produced by a build.

The op is named for creation, but it will also update a resource that already exists and, in one case, write nothing at all. Which of the three you get depends on what the data carries, not on anything you set on the form. Create or update works through it.

Fields

Resource Class

Which kind of resource to create. The list offers every resource class in the system, and the field holds one of them. Picking a second replaces the first.

The control also accepts free text, so a mistyped class name is saved without complaint and then stops the rule at run time when nothing by that name turns out to exist. Take the value from the list.

The form marks the field required. An op saved with it empty stops the rule the first time it runs.

Resource data (YAML map)

The fields of the new resource, written as YAML. Keys are field ids, not the labels you see on the resource form. Open an existing resource of the same class to read the ids off it. The hint beside the label says the same thing, and a YAML crib sheet sits under the editor.

${var} placeholders expand against the stash at any nesting depth, inside list entries as well as plain values. Value helpers work too, so ${lc(foo_user.login)} lowercases what it reads. A placeholder whose variable is not in the stash at all is left alone rather than emptied, so the literal text ${foo_user.login} ends up stored in the field. That is at least visible in the created resource, which an empty value would not be.

A key the class does not recognise is dropped without a word. That is the usual cause of a resource created with half its data missing: one wrong field id and the value is gone, with no error and nothing in the log. Check the created resource the first time you run a new configuration.

A value of the wrong shape, a list where a single value is expected for instance, stops the rule.

Fields that hold other resources take resource identifiers, one on its own or a YAML list of them. Each one is resolved while the resource is being built, so an identifier that matches nothing stops the rule there and then with a message naming it. Once saved, these values live as relationships between resources, which is why they show up in the resource graph rather than as ordinary fields.

A field:value lookup works in the same place, so name:bar_repo finds a resource by name instead of by identifier. The search is not restricted to the class the field expects, and it is not restricted to one class at all, so a name used by two resources anywhere in the system stops the rule with a message listing both identifiers.

Set created_by yourself if you want the resource to carry an author. Left out, it is written empty and the resource shows no creator in its history.

The YAML is parsed when you save the op. Invalid YAML raises a dialog and blocks the save. Comments are discarded, and the keys come back sorted alphabetically the next time you open the form, so keep any explanation on the op's Note tab.

An empty map is legal. It creates a resource holding nothing but the defaults of the class.

Create or update

Three outcomes, and the data picks between them.

The data carries a mid that matches a stored resource, and that resource is updated in place. The update writes back every field the class gives a default to, not only the ones you listed, so the creation timestamp moves to now, the author is blanked unless you supply created_by again, and a resource somebody had deactivated comes back active. Fields the class has no default for keep what they had.

The data carries an ns value that some resource of the same class already uses, and no mid. Then nothing happens. No resource is created, the stored one is not touched, and the op does not fail. A rule that sets ns from a stash variable therefore creates the resource on its first run and quietly does nothing on every run after that. Supply the stored resource's mid when you want the second run to update it.

Neither of those, and a new resource is created and given an identifier.

Classes that declare a field as unique stop the op with a duplicate key error naming that field rather than reusing anything, so a second local artifact repository with the same URL prefix fails instead of overwriting the first.

Creating and updating each raise their own event, which event rules can subscribe to.

What the op gives back

The op returns the resource. Put a name in the op's Return Key property to capture it, and later ops read ${myvar.mid}, ${myvar.name} and any other field of it. The identifier is the value you pass to any op that takes a resource.

On the namespace path there is no identifier to hand back, so ${myvar.mid} comes back empty. That is the cheapest way to tell at run time that the op wrote nothing.

Return Key set to = does nothing here. That setting spreads a returned record across the stash as separate variables, and a resource is not a plain record, so the merge is skipped in silence.

Nothing is undone on rollback. A resource created on the way forward is still there after the job rolls back. Delete it explicitly on the rollback path when that matters.

Past the debug line the rule engine records for every op, this one writes nothing to the job log. A run that created the wrong thing leaves no trace but the resource itself.

Combining with other ops

Capture the result and use it. SET VAR can reshape the returned values, and Invoke Resource methods acts on the resource the op returned.

Guard the op when the rule might run twice and you do not want a second resource. Read the stash with IF var condition THEN, or set a namespace so the duplicate run writes nothing.

For attaching the new resource to a topic or a project, follow it with the topic ops such as Create a new topic.

Examples

Register a user coming from a directory lookup, normalising the login to lower case and putting them in a group by resource identifier.

Resource Class   user
Resource data (YAML map):
  username: ${lc(foo_user.login)}
  name: ${lc(foo_user.login)}
  realname: ${foo_user.display_name}
  email: ${foo_user.mail}
  groups:
    - UserGroup-137
  language_pref: en

Record a revision produced by a build, linked to the repository resource it came from.

Resource Class   GitRevision
Resource data (YAML map):
  name: ${branch_sha}
  sha: ${branch_sha}
  repo: ${foo_repo.mid}

Register a package once per name. The namespace keeps a second run from creating a duplicate, and that second run writes nothing at all.

Resource Class   ArtifactRevision
Resource data (YAML map):
  name: ${package_name}
  moniker: ${package_name}
  ns: artifact/${package_name}
  uri: ${package_name}
  active: 1
  bl: '*'
  repo:
    - ${foo_repo.mid}