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 UFM's GRPC server. After a stream or one call, the session is deleted so the server would not save the authorizations.

  • 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 - The unique identifier for the client you want to have
  • Username - The authentication username
  • Password – The authentication password
  • Token – The authentication token
  • Response: 

    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 respond. 
  • Console command: 

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

Create New Subscription


  • Description: Only after the server has established a session for this grpc client,add 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 subscriber identifier
  • apiParams – The list of apiParams from the above message above:
    • ufm_api_name – The name from the known to server request api list
    • interval – The interval between messages conducted in a stream run. Presented in seconds.
    • only_delta – Receives the difference between the previous messages in a stream run.
  • Response content type: 

    message SessionRespond{
      string respond=1;
    }
  • Respond Types:
    • Created a user with session and added new IP– Ok.
    • Cannot add subscriber that do no have an established session – need to create a session before creating subscriber.
    • The server already have the ID – need to create new session and new subscriber with a new unique ID.
  • Console command: 

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

The API’s list is separated by commas, and each modifier for the REST API is separated by a semi comma.

If the server is not given a modifier, default ones are used (where only_delta is False and interval is based on the API).

Edit Known Subscription

  • Description: Changes a known IP. Whether the server has the IP 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 – The subscriber unique identifier
  • apiParams – A list of apiParams from the above message.
    • ufm_api_name – name from the known to server request api list
    • interval – The interval between messages conducted in a stream run. Presented in seconds.
    • only_delta – Receives the difference between the previous messages in a stream run.
  • Response content type: 

    message SessionRespond{
      string respond=1;
    }
  • Respond Types:
    • Created user with new IP– Ok. 
    • Cannot add subscriber without an established session – need to create a session before creating subscriber.
    • Cannot add subscriber illegal apis – cannot create subscriber with empty API list, call again with correct API list.

Get List of Known Subscribers

  • Description: Gets the list of subscribers, including the requested list of APIs.
  • 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 an existing subscriber and removes the session.
  • Call: DeleteSubscriber
  • Request Content Type: Message gRPCStreamerID
  • Request Data: 

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

Run a Known Subscriber Once

  • Description: Runs the Rest API list for a known subscriber once and returns the result in message runOnceRespond, and then delete the subscriber's 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- The first message unique identifier.
  • Results – list of gRPCStreamerParams contains results from each REST API
  • Responses:
    • Job id - Cannot run a client without an established session. Empty results – an existing session for this client is not found, and the client is not known to the server.
    • Job id - Cannot run the client without creating a subscriber. Empty results – a session was created for the client but the subscription is not created.
    • Job_id - Cannot connect to the UFM. empty result – 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 is experiencing a problem.
    • Job_id - The first unique message identifier of the messages. Not empty results – Ok
  • Console command: 

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

 

Run Streamed Data of a Known Subscriber

  • Description: Run a stream of results from the Rest API list for a known Subscriber and return the result as interator, where each item is message gRPCStreamerParams. at the end, delete 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:
    • One message only containing "Cannot run a client without a session" – A session has not been established
    • No message – A session and/or a subscriber with this ID does not exist.
    • Messages with interval between with the modifiers – Ok
  • Console command: 

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

Run a New Subscriber Once 

  • Description: After ensuring that a session for this specific job ID is established, the server runs the whole REST API list for the new subscriber once and returns the following result in message runOnceRespond. This action does not save the subscribe ID or the established 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;
    }
  • Responses:
    • 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 messages' first unique identifier, and not an empty result – 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 creates a session for this specific client.
  • A token or the basic authorization is needed, not both.

Run New Subscriber Streamed Data

  • Description: After the server checks it has a session for this job ID, Run a stream of results from the Rest API list for a new Subscriber and return the result as interator, where each item is message gRPCStreamerParams. at the end, delete 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 equals to Cant run client without 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
  • console command also create session for that client.
  • no need for both token and basic authorization, just one of them.

 

Run A Serialization on All the Running Streams

  • Description: Run a serialization for each running stream. The serialization will return to each of the machines the results from the rest api list.
  • Call: Serialization
  • Request Content Type: google.protobuf.Empty
  • Response: google.protobuf.Empty


Stop a Running Stream

  • Description: Cancels running stream using the client id of the stream and stop it from outside, If found stop the stream.
  • Call: StopStream
  • Request Content Type: Message gRPCStreamerID
  • Request Data: 

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

Run a subscribe stream

  • Description: Create 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
  • 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.
  • Cannot be stop streamed using StopStream.
  • Console command: 

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

Get the 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 and the version of the plugin, 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;
    }