image image image image image

YOU ARE VIEWING AN OUTDATED DOCUMENT.

On This Page

Authentication

The following authentication types are supported: 

  • basic (/ufmRest)
  • token (/ufmRestV3)

Create a Session to UFM from gRPC

Description: Creates a session to receive REST API results from the gRPC server. After a stream or submitting a call once, the session is deleted so that the authorizations are not saved by the server.

  • Call: CreateSession in the gRPC
  • Request Content Type: message SessionAuth

  • Request Data: 

    message SessionAuth{
  string job_id=1;
  string username = 2;
  string password = 3;
  optional string token = 4;
}


    • Job_id - A unique identifier for the client
    • Username - Basic authentication username 
    • Password – Basic authentication password
    • Token – The authentication token 

  • Response content type: 

    message SessionRespond{
  string respond=1;
}
  • Respond types:
    • Success – Ok.
    • ConnectionError – UFM connection error (bad parameters or UFM is down).
    • Other exceptions – Details sent in the response.

  • Console command: 

    client session --server_ip=server_ip --id=client_id --auth=username,password --token=token

Create a New Subscription

  • Description: Only after the server has an established session for this gRPC client, the server adds all the requested REST APIs with intervals and delta requests.
  • Call: AddSubscriber
  • Request Content Type – Message SubscriberParams

  • Request Data: 

    message SubscriberParams{
  message APIParams {
    string ufm_api_name = 1;
    int32 interval = 2;
    optional bool only_delta = 3;
  }
  string job_id = 1;
  repeated APIParams apiParams = 2;
}


    • Job_id – A unique identifier of this subscriber
    • apiParams – A list of apiParams from the message above
    • ufm_api_name – A name from the supported REST API list of names
    • interval – The interval (in seconds) between messages that the server sends in a stream run
    • only_delta – Receive the difference between the previous messages in a stream run

  • Response content type: 

    message SessionRespond{
  string respond=1;
}
  • Response types:
    • Created user with session and added a new IP address – Ok.
    • Cannot add subscriber without an established session – need to create a session before creating a subscriber.
    • The server already has the ID – need to create a new session and a new subscriber with a unique ID.

  • Console command: 

    client create --server_ip=localhost --id=client_id --apis=events;40;True,links,alarms;10


    • The list of APIs is separated by commas, and the modifiers of each REST API is separated by a semi comma.
    • If the modifiers are not provided, the server uses default ones (where only_delta is False and interval is based on the API).

Edit a Known Subscription

  • Description: Changes a known IP address, even if the IP address exists on the server or not.
  • Call: AddSubscriber
  • Request Content Type: Message SubscriberParams

  • Request Data: 

    message SubscriberParams{
  message APIParams {
    string ufm_api_name = 1;
    int32 interval = 2;
    optional bool only_delta = 3;
  }
  string job_id = 1; //unique identifier for this job
  repeated APIParams apiParams = 2;
}


    • Job_id – A unique identifier of this subscriber.
    • apiParams – The list of apiParams from the above message
    • ufm_api_name – A name from the supported REST API list of names
    • interval – The interval in seconds between messages that the server sends in a stream run
    • only_delta – Receives only the difference between the previous messages in a stream run

  • Response content type: 

    message SessionRespond{
  string respond=1;
}
  • Response Types:
    • Created a user with a session and added a new IP address – Ok. 
    • Cannot add subscriber that does not have a session – need to create a session before creating a subscriber.
    • Cannot add subscriber illegal APIs – cannot create subscriber with empty API list, call again with correct API list.

Get a List of Known Subscribers

  • Description: Gets a list of subscribers including the requested API lists.
  • Call: ListSubscribers
  • Request Content Type: google.protobuf.Empty

  • Response: 

    message ListSubscriberParams{
  repeated SubscriberParams subscribers = 1;
}
  • Console command: server subscribes –-server_ip=server_ip

 

Delete a Known Subscriber

  • Description: Deletes the subscriber and session (if existing).
  • Call: DeleteSubscriber
  • Request Content Type: Message gRPCStreamerID

  • Request Data: 

    message gRPCStreamerID{
string job_id = 1;
}
  • Response: google.protobuf.Empty

Run a Known Subscriber Once 

  • Description: Runs the Rest API list once for a known subscriber and returns the result in message runOnceRespond, and then deletes the subscriber session.
  • Call: RunOnceJob
  • Request Content Type: Message gRPCStreamerID

  • Request Data: 

    message gRPCStreamerID{
string job_id = 1;
}

  • Response content type: 

    message runOnceRespond{
  string job_id=1;
  repeated gRPCStreamerParams results = 2;
}


    • Job_id- A unique identifier of the first message.
    • Results – A list of gRPCStreamerParams contains the results from each REST API list.
  • Respond:
    • Job id - Cannot run a client without an established session. Empty results – no session for this client, and the client is not known to the server.
    • Job id - Cannot run a client without creating a subscriber. Empty results – a session was created for this client, but not a subscription.
    • Job_id - Could not connect to the UFM. Empty results – the gRPC server cannot connect to the UFM machine and receive empty results, because it cannot create a subscriber with an empty API list. This means that the UFM machine has a problem or is shut down.
    • Job_id - The first unique identifier of the messages, and not empty results – Ok.

  • Console command: 

    client once_id --server_ip=server_ip --id=client_id

Run Streamed Data of a Known Subscriber

  • Description: Runs a stream of results from the Rest API list for a known subscriber and returns the result as an iterator, where each item type is a message gRPCStreamerParams. At the end, the server deletes the session.
  • Call: RunStreamJob.
  • Request Content Type: Message gRPCStreamerID.

  • Request Data: 

    message gRPCStreamerID{
string job_id = 1;
}

  • Response content type: iterator of messages gRPCStreamerParams: 

    message gRPCStreamerParams{
  string message_id = 1; // unique identifier for messages
  string ufm_api_name = 2; // what rest api receive the data from
  google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
  string data = 4; // data of rest api call
}
  • Response:
    • Only one message with data – no session.
    • No message – no session and/or no subscriber with this ID.
    • Messages with interval between with the modifiers – Ok.

  • Console command:

    client stream_id --server_ip=server_ip --id=client_id

Run New Subscriber Once

  • Description: After the server checks it has a session for this job ID, it runs the Rest API list for a new subscriber once and returns the result in message runOnceRespond. It does not save the subscriber ID or the session in the server.
  • Call: RunOnce
  • Request Content Type: Message SubscriberParams

  • Request Data: 

    message SubscriberParams{
  message APIParams {
    string ufm_api_name = 1;
    int32 interval = 2;
    optional bool only_delta = 3;
  }
  string job_id = 1; //unique identifier for this job
  repeated APIParams apiParams = 2;
}

  • Response content type:

    message runOnceRespond{
  string job_id=1;
  repeated gRPCStreamerParams results = 2;
}
  • Response:
    • Job id - Cannot run a client without an established session. Empty results – no session for this client.
    • Job_id - 0 – The gRPC server cannot connect to the UFM machine and receive empty results, or it cannot create a subscriber with an empty API list.
    • Job_id - The first unique identifier of the messages. Not empty results – Ok.

  • Console command:

    client once --server_ip=server_ip --id=client_id --auth=username,password -–token=token --apis=events;40;True,links;20;False,alarms;10
  • The console command also creates a session for this client.
  • Either a token or basic authorization is needed.


Run Streamed Data of a New Subscriber

  • Description: After the server checks it has a session for this job ID, it runs a stream of results from the Rest API list for a new subscriber and returns the result as an iterator, where each item is a message gRPCStreamerParams. At the end, it deletes the session.
  • Call: RunPeriodically
  • Request Content Type: Message SubscriberParams

  • Request Data:

    message SubscriberParams{
  message APIParams {
    string ufm_api_name = 1;
    int32 interval = 2;
    optional bool only_delta = 3;
  }
  string job_id = 1; //unique identifier for this job
  repeated APIParams apiParams = 2;
}
  • Response content type: iterator of messages gRPCStreamerParams
  • Response:
    • Only one message with data - Cannot run client without an established session - No session
    • Messages with intervals between with the modifiers – Ok

  • Console command:

    client stream --server_ip=server_ip --id=client_id --auth=username,password -–token=token --apis=events;40;True,links;20;False,alarms;10


    • The console command also creates a session for the client.
    • Either a token or a basic authorization is needed.

Run a Serialization on all Running Streams

  • Description: Runs a serialization for each running stream. The serialization returns results from the REST API list to each of the machines.
  • Call: Serialization
  • Request Content Type: protobuf.Empty
  • Response: google.protobuf.Empty

Stop a Running Stream 

  • Description: Cancels running streams using the client's stream ID and stops it from outside. 
  • Call: StopStream
  • Request Content Type: Message gRPCStreamerID

  • Request Data:

    message gRPCStreamerID{
string job_id = 1;
}
  • Response: google.protobuf.Empty


Run a Subscribe Stream

  • Description: Creates a subscription to a client identifier. All new messages that go to that client, will be copied and also sent to this stream. 
  • Call: Serialization SubscribeToStream 
  • Request Content Type: message gRPCStreamerID

  • Response: iterator of messages gRPCStreamerParams

    message gRPCStreamerParams{
  string message_id = 1; // unique identifier for messages
  string ufm_api_name = 2; // what rest api receive the data from
  google.protobuf.Timestamp timestamp = 3; //what time we created the message, can be converted to Datetime
  string data = 4; // data of rest api call
}
  • The identifier may or may not be in the gRPC server.
  • Streams cannot be stopped using StopStream.

  • Console command: 

    client subscribe --server_ip=server_ip --id=client_id


Get Variables from a Known Subscriber

  • Description: Get the variables of known subscriber (if found), else return empty variables.
  • Call: GetJobParams
  • Request Content Type: message gRPCStreamerID

  • Response:

    message SubscriberParams{
  message APIParams {
    string ufm_api_name = 1; //currently the list of api from ufm that are supported are [Jobs, Events, Links, Alarms]
    int32 interval = 2;
    optional bool only_delta = 3;
  }
  string job_id = 1; //unique identifier for this job
  repeated APIParams apiParams = 2;
}

Get Help / Version

  • Description: Get help, plugin version, and information on how to interact with the server. What stages need to be done to extract the REST APIs (Session>run once/stream or Session>AddSubscriber>once_id/stream_id)
  • Call: Help or Version
  • Request Content Type: google.protobuf.Empty

  • Response:

    message SessionRespond{
  string respond=1;
}