ticket_abstractor_client 1.29.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ded94f5c8180e052cbbba7965f0b6b6f7bd94b7
-  data.tar.gz: 32c5b422fc531494a18993ffd332e50468c0dce2
+  metadata.gz: 2f77ae69e14119d1c04b675f194ab509d4ef4811
+  data.tar.gz: 91ee14717bae9af3f5509f126adc953b35c3d657
 SHA512:
-  metadata.gz: 5d57ad91f99f3627d536db958c38badeaa534b75b7ad1077a2c52b2226918531d61a22c03bcccafd33afe0ac89f223cb95c29168aa0bee21c70ae2c16729820d
-  data.tar.gz: 53c287a4c36de38fdbec00005fb1294bbc72f67e977199246760abaa29409e3e405d8cd910d4c8b92b47683cb78ccda312a5af0b03ed0fad0140aaaebe8d486f
+  metadata.gz: 7e7bfd5ec20c8c895578c8c5ace59cca3d0ead66752ec77040cb1ef29e6a89221428386f449ee5be1e7deb062b4faaa2961601a2fa4236073867c11d2b932daa
+  data.tar.gz: 8ba2f3595bd40ef1b19068ae3c07102ba75cca7028fdf61eb939e85fba1e79f5eb1413c4bf6a52b09c667c642bd586b641173db3f9ada2c931da183c2b69f34e

data/README.md

@@ -2,11 +2,21 @@
 
 Client for accessing to a TicketAbstractor service.
 
-## Installation
+## <a name="content"></a> Table of contents
+
+* [Installation](#installation)
+* [Upgrading](#upgrading)
+* [Configuration](#configuration)
+* [Usage](#usage)
+* [Filtering fields](#fields_filters)
+
+---
+
+## <a name="installation"></a> Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'ticket_abstractor_client'
+    gem 'ticket_abstractor_client', '>= 2.0.0'
 
 And then execute:
 
@@ -14,247 +24,277 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install ticket_abstractor_client
+    $ gem install ticket_abstractor_client -v '2.x'
 
-## API
+[[table of contents](#content)]
 
-[API Documentation](http://rubydoc.info/gems/ticket_abstractor_client/frames)
+---
 
-## Upgrading
+## <a name="upgrading"></a> Upgrading
 
-Since version 1.5.0, `TicketAbstractorClient.initialize_client` returns an instance of `TicketAbstractorClient::Base`
-instead of `TicketAbstractorClient` class.
+Since version 2.0.0, you operate with ticket as **PORO**.
 
-## Usage
+[[table of contents](#content)]
 
-Initialize:
+---
 
-    require 'ticket_abstractor_client'
+## <a name="configuration"></a> Configuration
 
-  without security token:
+**Base configuration options:**
 
-    client = TicketAbstractorClient.initialize_client('http://ticket.abstractor.url')
+    TicketAbstractorClient.configuration do |config|
+      config.ticket_abstractor_url = 'http://localhost:4567'
+      config.security_token = 'security_token_1'
+    end
 
-  with security token:
+**SSL options:**
 
-    client = TicketAbstractorClient.initialize_client('http://ticket.abstractor.url', 'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3')
+`DEFAULT_SSL_OPTIONS = { verify_ssl: true }`
 
-Access clients:
+For more available ssl options see **[SSL/TLS support](https://github.com/rest-client/rest-client#ssltls-support
+"RestClient SSL/TLS support")**
 
-    client.jira
-    client.brouha
-    client.itrc
-    client.ilogger
-    client.sev_one
-    client.service_now
+**JIRA specific options:**
 
-### Jira
+`jira_fields_meta` stores meta information about each JIRA field.
+Meta information is refreshed automatically after `jira_meta_expiration_period` (**604800**
+seconds by default, one week).
 
-Get list of Jira endpoints:
+Meta information can be manually updated:
 
-    client.jira.endpoints #=> { 'endpoint_name_1' => 'http://www.jira-endpoint.com', 'endpoint_name_2' => '... }
+    TicketAbstractorClient.configuration.jira_fields_meta = TicketAbstractorClient::ClientHelper.get_jira_fields_meta
 
-Get access to specific Jira instance:
+**ServiceNow specific options:**
 
-    client.jira.get_issue ... #=> default Jira instance (T&P)
-    client.jira('endpoint_name_1').get_issue ... #=> Jira at 'http://www.jira-endpoint.com'
+`snow_display_value`,
+based on this value, the display value and/or the actual value in the database are retrieved.
 
-Grab issue:
+* `SNOW_DISPLAY_VALUE_TRUE` returns display values for all of the fields.
+* `SNOW_DISPLAY_VALUE_FALSE` returns actual values from the database. If a value is not specified,
+this parameter defaults to false.
+* `SNOW_DISPLAY_VALUE_ALL` returns both actual and display values.
 
-    client.jira.get_issue 'IFS-123'
-    client.jira.get_issue_status 'IFS-123'
 
-Get issues by filter:
+    TicketAbstractorClient.snow_display_value = TicketAbstractorClient::Configuration::SNOW_DISPLAY_VALUE_ALL
 
-    jira_filter_id = 2145
-    client.jira.get_issues_by_filter jira_filter_id #=> [{ issue_1 }, { issue_2 }, ...]
-    client.jira.get_issues_by_filter jira_filter_id, page, per_page, show_total: true #=> { total: 2, issues: [...] }
+[[table of contents](#content)]
 
-Create issue (project, summary, description and issuetype fields are required):
+---
 
-    options = { project: "IFS", summary: "Summary", description: "Desc", issuetype: "Bug"}
-    client.jira.create_issue options
+## <a name="usage"></a> Usage
 
-Create issue with an attachment:
+* [Jira](#jira)
+* [ServiceNow](#snow)
 
-    options = { project: "IFS", summary: "Summary", description: "Desc", issuetype: "Bug"}
-    attachment = File.new('file.png', 'rb')
-    client.jira.create_issue options, attachment
+### <a name="jira"></a>Jira
 
-Create issue using Jira params:
+Get ticket by id:
 
-    options = { fields: { project: { key: "IFS" }, summary: "Summary", issuetype: { id: 82 } } }
-    attachment = File.new('file.png', 'rb')
-    client.jira.raw_create_issue options, attachment
+    # get issue from default Jira instance (T&P)
+    TicketAbstractorClient::Jira::Ticket.fetch_by_id(ticket_id: 'ISSUE-1')
 
-Update issue (issuekey field is required):
+    # get Jira endpoints
+    TicketAbstractorClient::Jira::Client.new.endpoints
 
-    client.jira.update_issue(issuekey: 'IFS-123', description: 'new description')
+    # get issue from specific endpoint
+    TicketAbstractorClient::Jira::Ticket.fetch_by_id(ticket_id: 'ISSUE-1', endpoint: :tp)
 
-Attach the file to issue:
+Get tickets by query:
 
-    attachment = File.new('file.png', 'rb')
-    client.jira.update_issue({ issuekey: 'IFS-123' }, attachment)
+    TicketAbstractorClient::Jira::Ticket.fetch_tickets_by_jql(query: 'project=ISSUE', endpoint: :tp)
 
-Create incident (project, summary, description and issuetype fields are required):
+Get ticket's comments:
 
-    options = { project: "IFS", summary: "Summary", description: "Desc", issuetype: {id: "3"},
-      customfields: {
-        customfield_1: {id: "22"},
-        customfield_2: {value: "No Impact"}
-      }}
-    client.jira.create_tvx_issue options
+    ticket = TicketAbstractorClient::Jira::Ticket.fetch_by_id(ticket_id: 'ISSUE-1')
+    ticket.comments
 
-Add comment to the issue (issuekey and comment fields are required):
+    # or
 
-    client.jira.add_comment(issuekey: 'IFS-123', comment: 'comment to ticket')
+    ticket_id = 'ISSUE-1'
+    endpoint = 'tp'
+    comments = TicketAbstractorClient::Jira::Comment.fetch(ticket_id, endpoint)
 
-Add an actiity to the issue (issuekey, comment and opts fields are required):
-opts should containt {generator: { id:, display_name:}, event_id:}
+Get ticket's attachments:
 
-    client.jira.add_activity(issuekey: 'IFS-123', comment: 'activity comment to ticket',
-      generator: {
-        id: 'https://intel.xcal.tv',
-        display_name: 'OIV'
-      },
-      event_id: '23456'
-    )
+    ticket = TicketAbstractorClient::Jira::Ticket.fetch(ticket_id: 'ISSUE-1')
+    ticket.attachments
 
-### Brouha
+    # or
 
-Grab issue:
+    ticket_id = 'ISSUE-1'
+    endpoint = 'tp'
+    attachments = TicketAbstractorClient::Jira::Attachment.fetch_by_id(ticket_id, endpoint)
 
-    client.brouha.get_issue '12'
+Create ticket:
 
-Create issue:
-
-    options = {
-      severity: 'Severity 5',
-      title: 'incident title',
-      bridge: '123456789',
-      summary: 'incident description',
-      product: 'Xfinity Voice',
-      service: 'voicemail',
-      division: 'incident division',
-      desk: 'incident desk',
-      opened_by: 'incident manager',
-      start_time: 'incident start time'
+    ticket_opts = {
+      endpoint: 'tp'
+      project: 'ISSUE'
+      fields: {
+        summary: "Example of ticket's summary",
+        description: "Example of ticket's description",
+        severity: 'Sev2',
+        priority: 'P2',
+        ...
+      }
     }
 
-    client.brouha.create_issue options
+    ticket = TicketAbstractorClient::Jira::Ticket.new(ticket_opts)
+    ticket.sync!
+    ticket.ticket_id # => ISSUE-111
 
-List products and services:
+Update ticket:
 
-    client.brouha.list_product_services
+    ticket_opts: {
+      endpoint: 'tp'
+      ticket_id: 'ISSUE-111'
+      fields: {
+        description: "Updated example of ticket's description",
+        severity: 'Sev3',
+        ...
+      }
+    }
 
-Update issue:
+    ticket = TicketAbstractorClient::Jira::Ticket.new(ticket_opts)
+    ticket.sync!
+    ticket.description # => "Updated example of ticket's description"
 
-    issue_key = 23
-    options = {
-      id: 23,
-      alarm_url: 'http://server.domain/alarms/'
-    }
+Update ticket's status:
 
-    client.brouha.update_issue issue_key, options
+    ticket = TicketAbstractorClient::Jira::Ticket.new(ticket_id: 'ISSUE-111', endpoint: 'tp')
+    ticket.status = 'IN_PROGRESS'
+    ticket.sync!
 
-### iTRC
+### <a name="snow"></a>ServiceNow
 
-Find apps:
+Get ticket by id:
 
-    client.itrc.list_apps
-    client.itrc.find_app 'itrc'
+    # get ServiceNow endpoints
+    TicketAbstractorClient::ServiceNow::Client.new.endpoints
 
-Find app_groups:
+    # get issue from specific endpoint
+    ticket_opts = { ticket_id: 'INC001', endpoint: :dev, project: 'incident' }
+    TicketAbstractorClient::ServiceNow::Ticket.fetch_by_id(ticket_opts)
 
-    client.itrc.list_app_groups
-    client.itrc.find_app_group 'app-mgmt-tools'
+Get tickets by query:
 
-Find business units:
+    ticket_opts = { query: 'numberIN(INC001,INC002,INC010)', endpoint: :test, project: 'incident' }
+    TicketAbstractorClient::ServiceNow::Ticket.fetch_tickets_by_query(ticket_opts)
 
-    client.itrc.list_business_units
-    client.itrc.find_business_unit 3
+Get ticket's comments:
 
-Find departments:
+    ticket_opts = { ticket_id: 'INC001', endpoint: :dev, project: 'incident' }
+    ticket = TicketAbstractorClient::ServiceNow::Ticket.fetch_by_id(ticket_opts)
+    ticket.comments
 
-    client.itrc.list_departments
-    client.itrc.find_department 4
+    # or
 
-### ILogger
+    ticket_id = 'INC001'
+    endpoint = 'default'
+    project = 'incident'
+    comments = TicketAbstractorClient::ServiceNow::Comment.fetch(ticket_id, endpoint, project)
 
-Grab incidents:
+Get ticket's attachments:
 
-    client.ilogger.get_incidents 'owner=brouha&incident_desk=ASD&limit=10&offset=0'
+    ticket_opts = { ticket_id: 'INC001', endpoint: :dev, project: :incident }
+    ticket = TicketAbstractorClient::ServiceNow::Ticket.fetch_by_id(ticket_opts)
+    ticket.attachments
 
-### SevOne
+    # or
 
-Get data from graph:
+    ticket_id = 'INC001'
+    endpoint = 'test'
+    project = 'incident'
+    attachments = TicketAbstractorClient::ServiceNow::Attachment.fetch(ticket_id, endpoint, project)
 
-    ## :graph => :data_sources is required
-    ## :timespan => :start_time and :end_time is required
-    params = {
-      graph: {
-        data_sources: [
-          { device_name: "ccprtr-br-a1-p", object_name: "ae1", indicator: "ifHCOutOctets" },
-          { device_name: "ccprtr-br-a2-p", object_name: "ae1", indicator: "ifHCOutOctets" }
-        ]
+Create ticket:
+
+    ticket_opts = {
+      endpoint: 'prod'
+      project: 'incident'
+      fields: {
+        short_title: "Example of ticket's summary",
+        title: "Example of ticket's description",
+        u_severity: 'Sev2',
+        u_priority: 'P2',
+        ...
       }
     }
 
-    ## query which fetch data for period(time in UNIX timestamp)
-    client.sev_one.report_get_data_from_graph(params.merge(timespan: { start_time: 1423242600.0, end_time: 1423242900.0 }))
-
-    ## query which fetch data for last 5 minutes
-    client.sev_one.report_get_data_from_graph(params.merge(timespan: { simple_timespan: "past 5 minutes" }))
+    ticket = TicketAbstractorClient::ServiceNow::Ticket.new(ticket_opts)
+    ticket.sync!
+    ticket.ticket_id # => INC011
 
-Get data from flowfalcon graph:
+Update ticket:
 
-    ## :graph => :data_sources is required
-    ## :timespan => :start_time and :end_time is required
-    params = {
-      graph: {
-        data_sources: [
-          { device_name: "68.87.7.129" },
-          { device_name: "68.87.7.130" }
-        ]
+    ticket_opts = {
+      endpoint: 'prod'
+      project: 'incident'
+      ticket_id: 'INC011'
+      fields: {
+        title: "Updated example of ticket's description",
+        u_severity: 'Sev3',
+        ...
       }
     }
 
-    ## query which fetch data for period(time in UNIX timestamp)
-    client.sev_one.flowfalcon_get_data_from_graph(params.merge(timespan: { start_time: 1423242600.0, end_time: 1423242900.0 }))
+    ticket = TicketAbstractorClient::ServiceNow::Ticket.new(ticket_opts)
+    ticket.sync!
+    ticket.short_title # => "Updated example of ticket's description"
 
-### Service Now
+Update ticket's status:
 
-    ## get all incidents:
-    client.service_now.get_all_incidents(limit: '1000', offset: '0', table_name: 'incident')
+    ticket_opts = { ticket_id: 'INC011', endpoint: 'tp', project: :prod }
+    ticket = TicketAbstractorClient::ServiceNow::Ticket.new(ticket_opts)
+    ticket.status = 'IN_PROGRESS'
+    ticket.sync!
 
-    # service_desk - is assigment_group in ServiceNow API. It should be escaped
-    # states - get incidents included in this states. It should be integers separated by comma
-    client.service_now.get_all_incidents(service_desk: 'T%26P+Prod+Support', states: '1,2,9,10,11')
 
-    # get incident:
-    # :incident_id is a required parameter
-    client.service_now.get_incident(incident_id: '', table_name: 'incident')
+[[table of contents](#content)]
 
-    # create incident:
-    # :incident_params is a required parameter
-    client.service_now.create_incident(incident_params: {}, table_name: 'incident')
+---
 
-    # update incident
-    # :incident_params and :sys_id is a required parameters
-    client.service_now.update_incident(incident_params: {}, sys_id: '', table_name: 'incident')
+## <a name="fields_filters"></a> Filtering fields
 
-    # get comments
-    # :incident_id is required parameter.
-    client.service_now.get_comments(incident_id: '', table_name: 'incident', display_value: false)
+There is a situation when you need to convert some values, like datetimes, or skip any other values and so on,
+before you start working with fetched ticket.
+All you have to do is create a class that is inherited from `TicketAbstractorClient::Base::FieldsFilter`
+and implement a `filter_fields` method, after that configure the gem to use your class.
 
-    # get all assignment groups:
-    client.service_now.get_all_groups()
-    client.service_now.get_all_groups(query: 'activeIStrue', limit: '100', fields: 'name,sys_id')
+**ServiceNow example:**
 
-## Contributing
+    class MyServiceNowTicketsFilter < TicketAbstractorClient::Base::FieldsFilter
+      def initialize(raw_fields)
+        super(raw_fields)
+      end
+
+      def filter_fields
+        self.raw_fields.each_with_object([]) |raw_field, filtered_fields|
+          # do some filtering here
+        end
+      end
+    end
+
+Add a line to configuration
+
+    ...
+    config.snow_fields_filter_class = MyServiceNowTicketsFilter
+    ...
+
+That's it.
+
+JIRA is supported as well.
+
+[[table of contents](#content)]
+
+---
+
+## <a name="contributing"></a> Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+[[table of contents](#content)]