Merge pull request #21 from ingrammicro/v15-development

Changes for V15

README.md

@@ -7,23 +7,27 @@
 [![PHP Eye](https://img.shields.io/php-eye/apsconnect/connect-sdk.svg?style=flat&branch=master&label=PHP-Eye%20tested)](https://php-eye.com/package/apsconnect/connect-sdk)
 
 ## Getting Started
-Connect PHP SDK allows an easy and fast integration with [Connect](http://connect.cloud.im/) fulfillment API. Thanks to it you can automate the fulfillment of orders generated by your products.
+Connect PHP SDK allows an easy and fast integration with [Connect](http://connect.cloud.im/) fulfillment API and usage API. Thanks to it you can automate the fulfillment of orders generated by your products and report usage for it.
 
 In order to use this library, please ensure that you have read first the documentation available on Connect knowladge base article located [here](http://help.vendor.connect.cloud.im/support/solutions/articles/43000030735-fulfillment-management-module), this one will provide you a great information on the rest api that this library implements.
 
 ## Class Features
 
-This library may be consumed in your project in order to automate the fulfillment of requests, this class once imported into your project will allow you to:
+This library may be consumed in your project in order to automate the fulfillment of requests and perform the usage reporting, this class once imported into your project will allow you to:
 
 - Connect to Connect using your api credentials
 - List all requests, and even filter them:
-    - for a Concrete product
+    - for a concrete product
     - for a concrete status
+    - for a concrete asset
+    - etc..
 - Process each request and obtain full details of the request
 - Modify for each request the activation parameters in order to:
     - Inquiry for changes
     - Store information into the fulfillment request
 - Change the status of the requests from it's initial pending state to either inquiring, failed or approved.
+- Generate and upload usage files to report usage for active contracts and listings
+- Process usage file status changes
 - Generate logs
 - Collect debug logs in case of failure
 
@@ -35,7 +39,7 @@ Connect PHP SDK is available on [Packagist](https://packagist.org/packages/apsco
 ```json
 {
   "require": {
-    "apsconnect/connect-sdk": "^14.0"
+    "apsconnect/connect-sdk": "^15.0"
     }
 }
 ```
@@ -48,7 +52,7 @@ composer require apsconnect/connect-sdk --no-dev --prefer-dist --classmap-author
 
 Note that the `vendor` folder and the `vendor/autoload.php` script are generated by Composer
 
-## A Simple Example
+## A Simple Example of fulfillment
 
 ```php
 <?php
@@ -109,6 +113,9 @@ class ProductRequests extends \Connect\FulfillmentAutomation
                 throw new \Connect\Fail("Operation not supported:".$request->type);
         }
     }
+    public function processTierConfigRequest($tierConfigRequest){
+        //This method allows processing Tier Requests, in same manner as simple requests. Is requiered to be implemented since v15
+    }
 }
 
 //Main Code Block
@@ -125,3 +132,95 @@ try {
     print "Error processing requests:" . $e->getMessage();
 }
 ```
+
+## A Simple Example of reporting Usage Files
+
+```php
+class UploadUsage extends \Connect\UsageAutomation
+{
+    /**
+     * @param $listing
+     * @return bool|string
+     * @throws \Connect\Usage\FileCreationException
+     * @throws \Connect\Usage\FileRetrieveException
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function processUsageForListing($listing)
+    {
+        //Detect concrete Provider Contract
+        if($listing->contract->id === 'CRD-41560-05399-123') {
+            //This is for Provider XYZ, also can be seen from $listing->provider->id and parametrized further via marketplace available at $listing->marketplace->id
+            date_default_timezone_set('UTC'); //reporting must be always based on UTC
+            $usages = [];
+            array_push($usages, new Connect\Usage\FileUsageRecord([
+                'item_search_criteria' => 'item.mpn', //Possible values are item.mpn or item.local_id
+                'item_search_value' => 'SKUA', //Value defined as MPN on vendor portal
+                'quantity' => 1, //Quantity to be reported
+                'start_time_utc' => date('d-m-Y H:i:s', strtotime("-1 days")), //From when to report
+                'end_time_utc' => date("Y-m-d H:i:s"), //Till when to report
+                'asset_search_criteria' => 'parameter.param_b', //How to find the asset on Connect, typical use case is to use a parameter provided by vendor, in this case called param_b, additionally can be used asset.id in case you want to use Connect identifiers
+                'asset_search_value' => 'tenant2'
+            ]));
+            $usageFile = new \Connect\Usage\File([
+                'name' => 'sdk test',
+                'product' => new \Connect\Product(
+                    ['id' => $listing->product->id]
+                ),
+                'contract' => new \Connect\Contract(
+                    ['id' => $listing->contract->id]
+                )
+            ]);
+            $this->submitUsage($usageFile, $usages);
+            return "processing done"
+        }
+        else{
+            //Do Something different
+        }
+    }
+
+}
+
+//Main Code Block
+try {
+    $requests = new UploadUsage();
+    $requests->process();
+
+} catch (Exception $e) {
+    print "Error processing usage for active listing requests:" . $e->getMessage();
+}
+```
+
+## A Simple Example of automating workflow of Usage Files
+
+```php
+class usagefilesworkflow extends \Connect\UsageFileAutomation
+{
+    /**
+     * @param $usageFile
+     * @throws \Connect\Usage\Accept
+     * @throws \Connect\Usage\Delete
+     * @throws \Connect\Usage\Skip
+     * @throws \Connect\Usage\Submit
+     */
+    public function processUsageFiles($usageFile)
+    {
+        switch ($usageFile->status){
+            case 'invalid':
+                //vendor and provider may handle invalid cases different, probably notifying their staff
+                throw new \Connect\Usage\Delete("Not needed anymore");
+                break;
+            case 'ready':
+                //Vendor may move to file to provider
+                throw new \Connect\Usage\Submit("Ready for Provider");
+            case 'pending':
+                //Provider use case, needs to be reviewed and accept it
+                throw new \Connect\Usage\Accept("File looks good");
+            default:
+                throw new \Connect\Usage\Skip("not controled status");
+        }
+    }
+}
+
+$usageWorkflow = new usagefilesworkflow();
+$usageWorkflow->process(); //is possible to ask to process all via parsing true, only applicable for providers who automates own products
+```

composer.json

@@ -11,7 +11,8 @@
         "psr/container": "^1.0.0",
         "psr/log": "^1.0.0",
         "pimple/pimple": "^3.0",
-        "guzzlehttp/guzzle": "~6.0"
+        "guzzlehttp/guzzle": "~6.0",
+        "phpoffice/phpspreadsheet": "^1.6"
     },
     "require-dev": {
         "phpunit/phpunit": "^5.7",

phpunit.xml

@@ -57,5 +57,27 @@
         <testsuite name="RequestStructure">
             <file>tests/Unit/RequestStructureTest.php</file>
         </testsuite>
+        <testsuite name="TierRequests">
+            <file>tests/Unit/TierRequestTest.php</file>
+        </testsuite>
+        <testsuite name="Usage Responses">
+            <file>tests/Unit/AcceptTest.php</file>
+            <file>tests/Unit/AcceptResponseTest.php</file>
+            <file>tests/Unit/CloseTest.php</file>
+            <file>tests/Unit/DeleteTest.php</file>
+            <file>tests/Unit/RejectTest.php</file>
+            <file>tests/Unit/RejectResponseTest.php</file>
+            <file>tests/Unit/UsageSkipTest.php</file>
+            <file>tests/Unit/SubmitTest.php</file>
+            <file>tests/Unit/FileRetrieveExceptionTest.php</file>
+            <file>tests/Unit/FileCreationExceptionTest.php</file>
+        </testsuite>
+        <testsuite name="Usage Automation">
+            <file>tests/Unit/UsageAutomationBasicsTest.php</file>
+            <file>tests/Unit/UsageAutomationTest.php</file>
+        </testsuite>
+        <testsuite name="Usage File Automation">
+            <file>tests/Unit/UsageFileAutomationTest.php</file>
+        </testsuite>
     </testsuites>
 </phpunit>

src/Account.php

@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * This file is part of the Ingram Micro Cloud Blue Connect SDK.
+ *
+ * @copyright (c) 2019. Ingram Micro. All Rights Reserved.
+ */
+
+namespace Connect;
+
+/**
+ * Class Account
+ * @package Connect
+ */
+class Account extends Model
+{
+    /**
+     * @var
+     */
+    public $id;
+    /**
+     * @var
+     */
+    public $name;
+
+    /**
+     * @var
+     */
+
+    public $external_uid;
+
+    /**
+     * @var
+     */
+    public $external_id;
+
+    /**
+     * @var ContactInfo
+     */
+
+    public $contact_info;
+
+}

src/Activation.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * This file is part of the Ingram Micro Cloud Blue Connect SDK.
+ *
+ * @copyright (c) 2019. Ingram Micro. All Rights Reserved.
+ */
+
+namespace Connect;
+
+/**
+ * Class Account
+ * @package Connect
+ */
+class Activation extends Model
+{
+    /**
+     * @var
+     */
+    public $link;
+}

src/Agreement.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * This file is part of the Ingram Micro Cloud Blue Connect SDK.
+ *
+ * @copyright (c) 2019. Ingram Micro. All Rights Reserved.
+ */
+
+namespace Connect;
+
+/**
+ * Class Agreement
+ * @package Connect
+ */
+class Agreement extends Model
+{
+    /**
+     * @var
+     */
+    public $id;
+    /**
+     * @var
+     */
+    public $name;
+
+}

src/Assignee.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * This file is part of the Ingram Micro Cloud Blue Connect SDK.
+ *
+ * @copyright (c) 2019. Ingram Micro. All Rights Reserved.
+ */
+
+namespace Connect;
+
+/**
+ * Class Account
+ * @package Connect
+ */
+class Assignee extends Model
+{
+    /**
+     * @var
+     */
+    public $id;
+    /**
+     * @var
+     */
+    public $name;
+}

src/Choice.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * This file is part of the Ingram Micro Cloud Blue Connect SDK.
+ *
+ * @copyright (c) 2019. Ingram Micro. All Rights Reserved.
+ */
+
+namespace Connect;
+
+/**
+ * Class Choice
+ * @package Connect
+ */
+class Choice extends Model
+{
+    /**
+     * @var
+     */
+    public $value;
+    /**
+     * @var
+     */
+    public $label;
+
+}