Storm Package: optic

The following Commands are available from this package. This documentation is generated for version 2.125.0 of the package.

Storm Commands

This package implements the following Storm Commands.

optic.messages.delete

Delete either a single user's copy of a message, or every copy.

Examples:

  // Delete the current user's copy of a message
  optic.messages.delete aa3254d9ffb15970f1be33f1f9e5ca1a

  // Delete another user's copy of a message
  optic.messages.delete e66bf9c3e04b0675468ef7c7810da419 --name visi

  // Delete every copy of a message
  optic.messages.delete aa3254d9ffb15970f1be33f1f9e5ca1a --all


Usage: optic.messages.delete [options] <iden>

Options:

  --help                      : Display the command usage.
  --name <name>               : Delete another user's instance of a message.
  --all                       : Delete every user's instance of a message.

Arguments:

  <iden>                      : The iden of the message to delete.

optic.messages.list

List all of a user's messages.

Examples:

  // Print all of visi's messages, newest to oldest.
  optic.messages.list visi

  // Print all of visi's messages, oldest to newest.
  optic.messages.list visi --ascending

Usage: optic.messages.list [options] <name>

Options:

  --help                      : Display the command usage.
  --ascending                 : Yield the messages oldest to newest.

Arguments:

  <name>                      : The name of the user to list messages for.

optic.messages.send

Send a message to users or roles.

Examples:

  // Send a message to a specific set of users
  optic.messages.send "Hi guys!" visi infime rakuyo

  // Send a JSON blob to a user
  optic.messages.send ({"stuff": "yes"}) --bodytype json visi

  // Send a message to every user in a role
  optic.messages.send "Hello there General Kenobi" --roles jedi sith


Usage: optic.messages.send [options] <message> <names>

Options:

  --help                      : Display the command usage.
  --subject <subject>         : A brief summary of the message.
  --bodytype <bodytype>       : The data type of the message body. (default: markdown, choices: text, markdown, json)
  --roles                     : Treat the list of names as a list of role names to message instead.

Arguments:

  <message>                   : The message to send. It can be either a string or JSON data.
  <names> [<names> ...]       : The name of the user(s) to message.

optic.spotlight.add

Add a new Optic Spotlight document.

Examples:
  // From the sha256 of a file:bytes node
  $file = effdaed49f73acc6ff718384a38108a9cb26080d322f7a277095b75acaa08576
  optic.spotlight.add 'file arg doc' --file $file

  // From the GUID of a media:news node
  $news = baf2bc3d697e5e8239f80e1f60e3ec41
  optic.spotlight.add 'news arg doc' --news $news

  // From a $url arg
  $url = https://vertex.link
  optic.spotlight.add 'url arg doc' --url $url

  // From a file:bytes node
  file:bytes=$sha256 optic.spotlight.add 'file:bytes node doc'

  // From a media:news node
  media:news=$guid optic.spotlight.add 'news node doc'

  // From a inet:url node
  inet:url=$url optic.spotlight.add 'url node doc'


Usage: optic.spotlight.add [options] <name>

Options:

  --help                      : Display the command usage.
  --file <file>               : The sha256 of the file:bytes node to use to create the Document.
  --news <news>               : The guid of the media:news node to use to create the Document.
  --url <url>                 : A url to use to create the Document.
  --yield                     : Yield the newly created media:news node.

Arguments:

  <name>                      : The name of the Spotlight document.

The command is accessible to users with one or more of the following permissions:

optic.spotlight.admin
optic.spotlight.user

optic.spotlight.del

Delete a Spotlight document by iden.

Usage: optic.spotlight.del [options] <iden>

Options:

  --help                      : Display the command usage.

Arguments:

  <iden>                      : The iden of the Spotlight document to delete.

optic.spotlight.list

List all Optic Spotlight documents you have at least viewer permission on and have their media:news node visible in your View.

Examples:

  // List Documents you can view and have media:news nodes in your View.
  optic.spotlight.list

  // List all Documents you can view regardless of if the media:news node is visible in your View.
  optic.spotlight.list --all


Usage: optic.spotlight.list [options]

Options:

  --help                      : Display the command usage.
  --all                       : Optionally see all documents regardless of whether the media:news node is visible in
                                your View.

optic.spotlight.set

Set a property of a Spotlight document.

The following props can be set:
  * name: The name of the Document.

Examples:

  // Set the Document name
  optic.spotlight.set $dociden name 'My Document Name'


Usage: optic.spotlight.set [options] <iden> <prop> <value>

Options:

  --help                      : Display the command usage.

Arguments:

  <iden>                      : The iden of the Document to update.
  <prop>                      : The Document prop to update.
  <value>                     : The value to set.

optic.stories.add

Add a new Optic Story.

Examples:

  // Add a story
  optic.stories.add 'My Story' --description 'A foo story'


Usage: optic.stories.add [options] <title>

Options:

  --help                      : Display the command usage.
  --description <description> : A longer description of the Story.
  --type <type>               : A Story type.
  --status <status>           : A Story status.
  --orientation <orientation> : Deprecated - use --layout instead. (default: singlecolumn)
  --layout <layout>           : The layout of the Story. Can be singlecolumn, portrait, or landscape. (default:
                                singlecolumn)
  --vars <vars>               : The vars associated with the Story. Can be a dict or a YAML string (with comments).

Arguments:

  <title>                     : The title of the Story.

The command is accessible to users with one or more of the following permissions:

optic.story.add

optic.stories.copy

Copy a Story by iden.

Usage: optic.stories.copy [options] <iden>

Options:

  --help                      : Display the command usage.
  --title <title>             : Optional title to set on the new Story copy.

Arguments:

  <iden>                      : The iden of the Story to copy.

optic.stories.del

Delete a Story by iden.

Usage: optic.stories.del [options] <iden>

Options:

  --help                      : Display the command usage.

Arguments:

  <iden>                      : The iden of the Story to delete.

optic.stories.element.nodes

Yield all the nodes in a specific element of a story. Only the nodes that exist in the current
view will be lifted.

Examples:
  // Yield all the nodes in a story and tag them
  optic.stories.nodes $storyiden $elemiden | [ +#my.story.nodes ]


Usage: optic.stories.element.nodes [options] <storyiden> <elemiden>

Options:

  --help                      : Display the command usage.

Arguments:

  <storyiden>                 : The iden of the Story that contains an element to fetch nodes for.
  <elemiden>                  : The iden of the Story element to fetch nodes for.

optic.stories.list

List all Optic Stories you have at least viewer permission on.

Examples:

  // List Stories
  optic.stories.list

Usage: optic.stories.list [options]

Options:

  --help                      : Display the command usage.

optic.stories.nodes

Yield all the nodes in all the elements of a story. Only the nodes that exist in the current
view will be lifted.

Examples:
  // Yield all the nodes in a story and tag them
  optic.stories.nodes $storyiden | [ +#my.story.nodes ]

Usage: optic.stories.nodes [options] <iden>

Options:

  --help                      : Display the command usage.

Arguments:

  <iden>                      : The iden of the Story to fetch nodes for.

optic.stories.set

Set a property of a Story.

The following props can be set:
  * title: A title for the Story
  * description: A longer description for the Story
  * type: <story type>
  * status: <story status>
  * vars: dict | yaml string
  * style: dict

Examples:

  // Set the title
  optic.stories.set $storyiden title 'My Updated Title'

  // Set the status
  optic.stories.set $storyiden status 'in review'

  // Set the vars from a dict
  $vars = ({"foo": "foo value", "bar": true})
  optic.stories.set $storyiden vars $vars

  // Set the vars from a YAML string
  $vars = '''
  foo: foo value

  # document your YAML
  bar: true
  '''
  optic.stories.set $storyiden vars $vars


Usage: optic.stories.set [options] <iden> <prop> <value>

Options:

  --help                      : Display the command usage.

Arguments:

  <iden>                      : The iden of the Story to update.
  <prop>                      : The Story prop to update.
  <value>                     : The value to set.

Storm Modules

This package implements the following Storm Modules.

optic.messages

addRoleMesg(mesg, roles, subject=(null), bodytype=(null))

Send a message to a list of roles.

Args:

mesg (str): The message to send.

roles (list): The list of role idens to send the message to. This will be expanded to a list of users at message send time.

subject (str): An optional subject line for the message.

bodytype (str): An optional type for the message body. Currently supported values are “json” and “markdown”.

Returns:

The message and associated metadata. The return type is dict.

addUserMesg(mesg, roles, subject=(null), bodytype=(null))

Send a message to a list of users.

Args:

mesg (str): The message to send.

roles (list): The list of user idens to send the message to.

subject (str): An optional subject line for the message.

bodytype (str): An optional type for the message body. Currently supported values are “json” and “markdown”.

Returns:

The message and associated metadata. The return type is dict.

iterUserMesgs(user, reverse=(false), wait=(false))

Iterate over a user’s messages from oldest to newest.

Args:

user (str): The iden of the user to fetch messages for.

reverse (boolean): If true, iterate over the user’s messages from newest to oldest.

wait (boolean): If true, block on receiving new messages and message updates. Ignores the reverse parameter.

Yields:

A generator that yields message envelopes. The return type is dict.

modUserEnvelope(mesgiden, useriden, tick, info)

Modify a specific user’s copy of a message.

Args:

mesgiden (str): The iden of the message to modify.

useriden (str): The iden of the user the message was sent to.

tick (integer): The time the message was sent.

info (dict): Information to be set on a user’s copy of a message. Currently the only supported key is “read”, which is a boolean.

Returns:

Returns null. The return type is null.

delUserMesg(mesgiden)

Delete a message from every user who received it.

Args:: mesgiden (str): The iden of the message to delete.
Returns:: Returns null. The return type is null.

delUserEnvelope(mesgiden, useriden)

Delete a message from a specific user.

Args:

mesgiden (str): The iden of the message to delete.

useriden (str): The iden of the user who received the message.

Returns:

Returns null. The return type is null.

optic.stories

list()

Get all the Stories you have at least viewer access to.

Returns:: The list of Stories the calling user has viewer access to. The return type is list.

get(iden)

Get a specific Story by iden.

Args:: iden (str): The iden of the Story to fetch.
Returns:: The Story dictionary. The return type is dict.

add(sdef)

Add a new Story. sdef can contain:

title: A title for the Story
description: A longer description for the Story
type: <Story type>
status: <Story status>
layout: singlecolumn | portrait | landscape
vars: dict | yaml string
style: dict

Args:

sdef (dict): The initial state of the Story.

Returns:

The Story dictionary. The return type is dict.

del(iden)

Delete a specific Story by iden.

Args:: iden (str): The iden of the Story to delete.
Returns:: Whether the Story was successfully deleted or not. The return type is boolean.

nodes(storyiden)

Get all the nodes associated with a Story.

Args:: storyiden (str): The iden of the Story to fetch nodes for.
Yields:: Lifts the nodes associated with the Story by iden. The return type is node.

elementNodes(storyiden, elemiden)

Get all the nodes associated with a specific element in a Story.

Args:

storyiden (str): The iden of the Story to fetch nodes for.

elemiden (str): The iden of the element in the Story to fetch nodes for.

Yields:

Lifts the nodes associated with the element in a Story by iden. The return type is node.

set(storyiden, prop, value)

Set a property of a Story. The following properties can be set:

title: A title for the Story
description: A longer description for the Story
type: <Story type>
status: <Story status>
vars: dict | yaml string
style: dict

Args:

storyiden (str): The iden of the Story to set the property on.

prop (str): The property to set.

value (str): The new value to set the property to.

Returns:

Whether the Story property was successfully updated or not. The return type is boolean.

copy(iden, title)

Make a copy of a Story and optionally set the title of the new Story.

Args:

iden (str): The iden of the Story to copy.

title (str): An optional title for the new Story.

Returns:

The Story dictionary. The return type is dict.

grant(storyiden, scope, iden, perm)

Grant a user or role permissions on a Story.

Args:

storyiden (str): The iden of the Story to grant permissions on.

scope (str): Either the value “user” or the value “role”.

iden (str): A user iden or role iden, depending on the value given to scope.

perm (str): Either “viewer”, “editor”, or “admin”.

Returns:

Whether the Story permissions were successfully updated or not. The return type is boolean.

revoke(storyiden, scope, iden)

Revoke a user or role’s permissions on the Story.

Args:

storyiden (str): The iden of the Story to revoke permissions from.

scope (str): Either the value “user” or the value “role”.

iden (str): A user iden or role iden, depending on the value given to scope.

Returns:

Whether the Story permissions were successfully updated or not. The return type is boolean.

optic.ui

changeView(viewiden, useriden=(null))

Change the given user’s view to the specified one.

Args:

viewiden (str): The iden of the view to change to.

useriden (str): The iden of the user to change the view for. If null, it defaults to the calling user.

Returns:

Whether the message was successfully sent to the Optic instance or not. The return type is boolean.

toast(level, mesg, useriden=(null))

Send a toast to a user’s Optic session.

Args:

level (str): The severity level of the toast. Currently supported values are “error”, “warn”, “success”, and “verbose”.

mesg (str): The message to display to the user.

useriden (str): The iden of the user to send the toast to. If null, it defaults to the calling user.

Returns:

Whether the message was successfully sent to the Optic instance or not. The return type is boolean.

navTool(tool, useriden=(null))

Navigate a user’s current Optic tool to the specified tool. If the tool is gated by a feature flag as noted in the Devops Guide, the feature flag must be enabled.

Args:

tool (str): The name of the tool to navigate to. Currently supported values are “research”, “spotlight”, “bulkingest”, “storm-editor”, “stories”, “workflows”, “console”, “workspaces”, “power-ups”, “metrics”, “messages”, “learning”, “help”, and “admin”.

useriden (str): The iden of the user to change the tool for. If null, it defaults to the calling user.

Returns:

Whether the message was successfully sent to the Optic instance or not. The return type is boolean.

openUrl(url, useriden=(null))

Open a new URL in the given user’s Optic session.

Args:

url (str): The URL to open.

useriden (str): The iden of the user to open the URL for. If null, it defaults to the calling user.

Returns:

Whether the message was successfully sent to the Optic instance or not. The return type is boolean.

researchQuery(query, displaymode, querymode, useriden=(null))

Switch a user’s Optic session to the Research tool, set the Display and Query modes, and run a query.

Args:

query (str): The Storm query to run.

displaymode (str): The Display mode to switch to. Currently supported values are “table”, “force”, “geospatial”, “stats”, “tree”, and “timeline”. If selecting “tree” or “timeline”, those features must be enabled in your Optic instance (see the Devops Guide for more details).

querymode (str): The Storm query mode to switch to. Currently supported values are “storm”, “lookup”, “autoadd”, and “search”. If selecting “search”, Synapse-Search must be enabled in your Synapse instance.

useriden (str): The iden of the user to run the query for. If null, it defaults to the calling user.

Returns:

Whether the message was successfully sent to the Optic instance or not. The return type is boolean.